fix(im): remove unsupported feed group shortcuts

Remove the feed group list/query shortcut registration, implementation, tests, and skill references so the im domain no longer exposes unsupported feed group commands.

Keep the remaining im flag validation paths on typed error envelopes.

.golangci.yml

@@ -73,20 +73,20 @@ linters:
           - forbidigo
       # errs-typed-only enforced on paths already migrated to errs.NewXxxError.
       # Add a path when its migration is complete.
-      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/)
+      - path-except: (internal/auth/|internal/errcompat/|internal/errclass/|internal/client/|internal/cmdutil/factory\.go|cmd/auth/|cmd/config/|cmd/service/|shortcuts/common/mcp_client\.go|shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/im/)
         text: errs-typed-only
         linters:
           - forbidigo
       # errs-no-bare-wrap enforced on paths fully migrated to typed final
       # errors. Scoped separately from errs-typed-only because cmd/auth/,
       # cmd/config/ still have residual fmt.Errorf and must not be caught.
-      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/|shortcuts/common/mcp_client\.go)
+      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/im/|shortcuts/common/mcp_client\.go)
         text: errs-no-bare-wrap
         linters:
           - forbidigo
       # errs-no-legacy-helper enforced on domains whose shared validation/save
       # helpers have migrated to typed final errors.
-      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/im/|shortcuts/mail/|shortcuts/minutes/|shortcuts/okr/|shortcuts/task/|shortcuts/vc/|shortcuts/whiteboard/)
+      - path-except: (shortcuts/base/|shortcuts/calendar/|shortcuts/drive/|shortcuts/mail/|shortcuts/okr/|shortcuts/task/|shortcuts/whiteboard/|shortcuts/im/)
         text: errs-no-legacy-helper
         linters:
           - forbidigo

cmd/build.go

@@ -6,7 +6,6 @@ package cmd
 import (
 	"context"
 	"io"
-	"io/fs"
 
 	"github.com/larksuite/cli/cmd/api"
 	"github.com/larksuite/cli/cmd/auth"
@@ -17,7 +16,6 @@ import (
 	"github.com/larksuite/cli/cmd/profile"
 	"github.com/larksuite/cli/cmd/schema"
 	"github.com/larksuite/cli/cmd/service"
-	"github.com/larksuite/cli/cmd/skill"
 	cmdupdate "github.com/larksuite/cli/cmd/update"
 	_ "github.com/larksuite/cli/events"
 	"github.com/larksuite/cli/internal/build"
@@ -53,18 +51,6 @@ func WithKeychain(kc keychain.KeychainAccess) BuildOption {
 	}
 }
 
-// embeddedSkillContent is the skill tree wired into cmdutil.Factory.SkillContent
-// at build time. It is registered by the repo-root package main's init via
-// SetEmbeddedSkillContent — it cannot be threaded through main.go without
-// breaking the single-file preview build (see skills_embed.go). nil in builds
-// that embed no skills; the `skills` commands then return a typed internal error.
-var embeddedSkillContent fs.FS
-
-// SetEmbeddedSkillContent registers the embedded skill tree. Called from the
-// repo-root package main's init; a wrapper main can call it before Execute to
-// supply its own skill content.
-func SetEmbeddedSkillContent(fsys fs.FS) { embeddedSkillContent = fsys }
-
 // HideProfile sets the visibility policy for the root-level --profile flag.
 // When hide is true the flag stays registered (so existing invocations still
 // parse) but is omitted from help and shell completion. Typically called as
@@ -117,7 +103,6 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	if cfg.keychain != nil {
 		f.Keychain = cfg.keychain
 	}
-	f.SkillContent = embeddedSkillContent
 	rootCmd := &cobra.Command{
 		Use:     "lark-cli",
 		Short:   "Lark/Feishu CLI — OAuth authorization, UAT management, API calls",
@@ -155,7 +140,6 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	rootCmd.AddCommand(completion.NewCmdCompletion(f))
 	rootCmd.AddCommand(cmdupdate.NewCmdUpdate(f))
 	rootCmd.AddCommand(cmdevent.NewCmdEvents(f))
-	rootCmd.AddCommand(skill.NewCmdSkill(f))
 	service.RegisterServiceCommandsWithContext(ctx, rootCmd, f)
 	shortcuts.RegisterShortcutsWithContext(ctx, rootCmd, f)
 

cmd/skill/skill.go

@@ -1,183 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package skill implements the `lark-cli skills` command group, which serves
-// binary-embedded skill content to AI agents. The package is "skill"; the
-// user-facing verb is "skills".
-package skill
-
-import (
-	"fmt"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/skillcontent"
-	"github.com/spf13/cobra"
-)
-
-func newReader(f *cmdutil.Factory) (*skillcontent.Reader, error) {
-	if f.SkillContent == nil {
-		return nil, errs.NewInternalError(errs.SubtypeFileIO,
-			"skill content not embedded in this build")
-	}
-	return skillcontent.New(f.SkillContent), nil
-}
-
-type readEnvelope struct {
-	Skill    string `json:"skill"`
-	Path     string `json:"path"`
-	Content  string `json:"content"`
-	Guidance string `json:"guidance,omitempty"`
-}
-
-type listEnvelope struct {
-	OK     bool                     `json:"ok"`
-	Skills []skillcontent.SkillInfo `json:"skills"`
-	Count  int                      `json:"count"`
-}
-
-type listPathEnvelope struct {
-	OK      bool                    `json:"ok"`
-	Path    string                  `json:"path"`
-	Entries []skillcontent.DirEntry `json:"entries"`
-	Count   int                     `json:"count"`
-}
-
-func NewCmdSkill(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "skills",
-		Short: "Read embedded skill content (list / read)",
-		Long: "Read agent-readable skill content (SKILL.md and reference files) embedded in " +
-			"the CLI binary at build time, so it stays in sync with the CLI version. " +
-			"Machine resources such as assets/ and scripts/ are not embedded.",
-	}
-	// Risk is set on each leaf (GetRisk does not walk parents); the group has none.
-	cmdutil.DisableAuthCheck(cmd)
-	cmd.AddCommand(newListCmd(f), newReadCmd(f))
-	return cmd
-}
-
-func newListCmd(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "list [name[/path]]",
-		Short: "List skills, or list one layer under a skill path (like ls)",
-		Example: `  lark-cli skills list                      # all skills: name, description, version
-  lark-cli skills list lark-doc             # one layer under a skill (like ls)
-  lark-cli skills list lark-doc/references  # one layer under a subdirectory`,
-		Args: cobra.ArbitraryArgs,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if len(args) > 1 {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"list takes at most 1 argument: [name[/path]]").
-					WithHint("run 'lark-cli skills list --help'")
-			}
-			r, err := newReader(f)
-			if err != nil {
-				return err
-			}
-			if len(args) == 0 {
-				skills, err := r.List()
-				if err != nil {
-					return err
-				}
-				output.PrintJson(f.IOStreams.Out, listEnvelope{OK: true, Skills: skills, Count: len(skills)})
-				return nil
-			}
-			entries, listed, err := r.ListPath(args[0])
-			if err != nil {
-				return err
-			}
-			output.PrintJson(f.IOStreams.Out, listPathEnvelope{OK: true, Path: listed, Entries: entries, Count: len(entries)})
-			return nil
-		},
-	}
-	// --json is a no-op (list is always JSON), accepted only to stay symmetric with read.
-	cmd.Flags().Bool("json", false, "no-op (list output is always JSON)")
-	cmdutil.SetRisk(cmd, "read")
-	cmdutil.DisableAuthCheck(cmd)
-	return cmd
-}
-
-func newReadCmd(f *cmdutil.Factory) *cobra.Command {
-	var asJSON bool
-	cmd := &cobra.Command{
-		Use:   "read <name>[/<path>] [path]",
-		Short: "Print a skill's SKILL.md, or a file under the skill (raw markdown by default)",
-		Example: `  lark-cli skills read lark-doc                             # the skill's SKILL.md
-  lark-cli skills read lark-doc references/lark-doc-fetch.md  # a file under the skill
-  lark-cli skills read lark-doc/references/lark-doc-fetch.md  # same, slash form
-  lark-cli skills read lark-doc --json                      # JSON envelope`,
-		Args: cobra.ArbitraryArgs,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			name, relpath, err := parseReadTarget(args)
-			if err != nil {
-				return err
-			}
-			r, err := newReader(f)
-			if err != nil {
-				return err
-			}
-
-			var content []byte
-			var pathOut string
-			if relpath == "" {
-				content, err = r.ReadSkill(name)
-				pathOut = "SKILL.md"
-			} else {
-				content, pathOut, err = r.ReadReference(name, relpath)
-			}
-			if err != nil {
-				return err
-			}
-
-			isMain := pathOut == "SKILL.md"
-			if asJSON {
-				env := readEnvelope{Skill: name, Path: pathOut, Content: string(content)}
-				if isMain {
-					env.Guidance = readGuidance(name)
-				}
-				output.PrintJson(f.IOStreams.Out, env)
-				return nil
-			}
-			// Raw stdout stays byte-identical to the file; guidance goes to stderr.
-			if _, err := f.IOStreams.Out.Write(content); err != nil {
-				return errs.NewInternalError(errs.SubtypeFileIO, "failed to write output: %v", err)
-			}
-			if isMain {
-				fmt.Fprintln(f.IOStreams.ErrOut, readGuidance(name))
-			}
-			return nil
-		},
-	}
-	cmd.Flags().BoolVar(&asJSON, "json", false, "output as a JSON envelope instead of raw markdown")
-	cmdutil.SetRisk(cmd, "read")
-	cmdutil.DisableAuthCheck(cmd)
-	return cmd
-}
-
-// parseReadTarget maps 1-or-2 positional args to (name, relpath); a lone
-// "<a>/<b>" splits on the first '/', and relpath "" reads the main SKILL.md.
-func parseReadTarget(args []string) (name, relpath string, err error) {
-	switch len(args) {
-	case 1:
-		name, relpath = skillcontent.SplitArg(args[0])
-		return name, relpath, nil
-	case 2:
-		return args[0], args[1], nil
-	default:
-		return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"read requires 1 or 2 arguments: <name>[/<path>] [path]").
-			WithHint("run 'lark-cli skills read --help'")
-	}
-}
-
-// readGuidance routes cross-skill "../lark-foo/..." references back through
-// `skills read lark-foo/...`: the path guard rejects a literal "../", so the
-// relative form must be rewritten.
-func readGuidance(name string) string {
-	return fmt.Sprintf("> Tip: read this skill's own files (e.g. `references/...`) with "+
-		"`lark-cli skills read %s <relative-path>` to keep them in sync with this CLI version. "+
-		"A reference to another skill (`../lark-foo/...`) uses the same command with the "+
-		"leading `../` removed: `lark-cli skills read lark-foo/...`.", name)
-}

cmd/skill/skill_test.go

@@ -1,306 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package skill
-
-import (
-	"encoding/json"
-	"io"
-	"io/fs"
-	"strings"
-	"testing"
-	"testing/fstest"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-)
-
-// calFS is the default single-skill content tree for these tests. The embedded
-// FS is now injected through the Factory (no package global), so tests pass it
-// explicitly to run() — nothing is shared, so they are safe under -parallel.
-func calFS() fstest.MapFS {
-	return fstest.MapFS{
-		"lark-calendar/SKILL.md":             {Data: []byte("---\nname: lark-calendar\nversion: 1.0.0\ndescription: \"Cal\"\nmetadata:\n  cliHelp: \"lark-cli calendar --help\"\n---\nbody")},
-		"lark-calendar/references/agenda.md": {Data: []byte("# Agenda")},
-	}
-}
-
-// run executes the skills command tree against the given content FS (may be nil
-// to exercise the not-embedded path) and returns stdout/stderr/err.
-func run(t *testing.T, fsys fs.FS, args ...string) (stdout, stderr string, err error) {
-	t.Helper()
-	// Isolate CLI config state so tests never read/write the real config dir
-	// (repo convention).
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, out, errOut, _ := cmdutil.TestFactory(t, nil)
-	f.SkillContent = fsys
-	cmd := NewCmdSkill(f)
-	cmd.SetOut(io.Discard)
-	cmd.SetErr(io.Discard)
-	cmd.SetArgs(args)
-	err = cmd.Execute()
-	return out.String(), errOut.String(), err
-}
-
-func TestSkillList(t *testing.T) {
-	stdout, _, err := run(t, calFS(), "list")
-	if err != nil {
-		t.Fatalf("list error: %v", err)
-	}
-	var got struct {
-		OK     bool             `json:"ok"`
-		Skills []map[string]any `json:"skills"`
-		Count  int              `json:"count"`
-	}
-	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
-		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
-	}
-	// "ok" is an explicit success marker (the list envelope is a typed struct;
-	// no automatic _notice attaches).
-	if !got.OK {
-		t.Error("expected ok=true in list envelope")
-	}
-	if got.Count != 1 || len(got.Skills) != 1 {
-		t.Fatalf("count: got %d", got.Count)
-	}
-	if got.Skills[0]["name"] != "lark-calendar" {
-		t.Errorf("name: got %v", got.Skills[0]["name"])
-	}
-	// Top-level list carries version + metadata, not a references list.
-	if _, ok := got.Skills[0]["references"]; ok {
-		t.Error("top-level list must not include references")
-	}
-	if got.Skills[0]["version"] != "1.0.0" {
-		t.Errorf("version: got %v, want 1.0.0", got.Skills[0]["version"])
-	}
-	if _, ok := got.Skills[0]["metadata"]; !ok {
-		t.Error("expected metadata in list entry")
-	}
-}
-
-func TestSkillListJSONFlagAccepted(t *testing.T) {
-	// `list --json` must be accepted (no-op), not rejected as an unknown flag,
-	// so it stays symmetric with read --json.
-	stdout, _, err := run(t, calFS(), "list", "--json")
-	if err != nil {
-		t.Fatalf("list --json error: %v", err)
-	}
-	var got struct {
-		OK    bool `json:"ok"`
-		Count int  `json:"count"`
-	}
-	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
-		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
-	}
-	if !got.OK || got.Count != 1 {
-		t.Errorf("envelope: %+v", got)
-	}
-}
-
-func TestSkillListPath(t *testing.T) {
-	stdout, _, err := run(t, calFS(), "list", "lark-calendar")
-	if err != nil {
-		t.Fatalf("list <name> error: %v", err)
-	}
-	var got struct {
-		OK      bool   `json:"ok"`
-		Path    string `json:"path"`
-		Entries []struct {
-			Path  string `json:"path"`
-			IsDir bool   `json:"is_dir"`
-		} `json:"entries"`
-		Count int `json:"count"`
-	}
-	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
-		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
-	}
-	if !got.OK || got.Path != "lark-calendar" {
-		t.Errorf("envelope: %+v", got)
-	}
-	// One layer under the skill root: SKILL.md (file) + references (dir).
-	if got.Count != 2 || len(got.Entries) != 2 {
-		t.Fatalf("entries: got %+v", got.Entries)
-	}
-	if got.Entries[0].Path != "lark-calendar/SKILL.md" || got.Entries[0].IsDir {
-		t.Errorf("entry[0]: got %+v", got.Entries[0])
-	}
-	if got.Entries[1].Path != "lark-calendar/references" || !got.Entries[1].IsDir {
-		t.Errorf("entry[1]: got %+v", got.Entries[1])
-	}
-}
-
-func TestSkillListPathUnknown(t *testing.T) {
-	_, _, err := run(t, calFS(), "list", "no-such-skill")
-	if err == nil || !strings.Contains(err.Error(), "unknown skill") {
-		t.Fatalf("expected 'unknown skill' error, got %v", err)
-	}
-}
-
-func TestSkillListPathTraversal(t *testing.T) {
-	stdout, _, err := run(t, calFS(), "list", "lark-calendar/../../etc")
-	if err == nil || !strings.Contains(err.Error(), "invalid path") {
-		t.Fatalf("expected 'invalid path' error, got %v", err)
-	}
-	if stdout != "" {
-		t.Errorf("stdout must be empty on rejection, got %q", stdout)
-	}
-}
-
-func TestSkillListTooManyArgs(t *testing.T) {
-	_, _, err := run(t, calFS(), "list", "a", "b")
-	if err == nil || !strings.Contains(err.Error(), "at most 1 argument") {
-		t.Fatalf("expected 'at most 1 argument' error, got %v", err)
-	}
-}
-
-// TestSkillListSkipsDirWithoutSKILLmd proves a top-level dir lacking SKILL.md is
-// omitted from the catalog (no blank entry).
-func TestSkillListSkipsDirWithoutSKILLmd(t *testing.T) {
-	fsys := fstest.MapFS{
-		"lark-calendar/SKILL.md": {Data: []byte("---\nname: lark-calendar\ndescription: \"Cal\"\n---\nb")},
-		"not-a-skill/readme.txt": {Data: []byte("junk")}, // dir without SKILL.md
-	}
-	stdout, _, err := run(t, fsys, "list")
-	if err != nil {
-		t.Fatalf("list error: %v", err)
-	}
-	var got struct {
-		Skills []map[string]any `json:"skills"`
-		Count  int              `json:"count"`
-	}
-	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
-		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
-	}
-	if got.Count != 1 || got.Skills[0]["name"] != "lark-calendar" {
-		t.Fatalf("expected only lark-calendar, got %+v", got.Skills)
-	}
-}
-
-func TestSkillReadRaw(t *testing.T) {
-	stdout, stderr, err := run(t, calFS(), "read", "lark-calendar")
-	if err != nil {
-		t.Fatalf("read error: %v", err)
-	}
-	if !strings.HasPrefix(stdout, "---\nname: lark-calendar") {
-		t.Errorf("raw output: got %q", stdout)
-	}
-	// Raw stdout is byte-pure SKILL.md — the guidance tip must NOT be appended.
-	if strings.Contains(stdout, "Tip:") {
-		t.Errorf("raw stdout must not carry the guidance tip: got %q", stdout)
-	}
-	// Guidance goes to stderr: own files via `skills read <name> ...`, and
-	// cross-skill refs routed to `skills read <other-skill> ...` (version-
-	// consistent), not "read directly".
-	if !strings.Contains(stderr, "lark-cli skills read lark-calendar <relative-path>") {
-		t.Errorf("expected own-files guidance on stderr: got %q", stderr)
-	}
-	if !strings.Contains(stderr, "lark-cli skills read lark-foo/...") {
-		t.Errorf("expected cross-skill refs routed to skills read: got %q", stderr)
-	}
-	if strings.Contains(stderr, "instead of opening them directly") ||
-		strings.Contains(stderr, "read those directly") {
-		t.Errorf("guidance must not steer cross-skill refs to direct reads: got %q", stderr)
-	}
-}
-
-func TestSkillReadJSON(t *testing.T) {
-	stdout, _, err := run(t, calFS(), "read", "lark-calendar", "--json")
-	if err != nil {
-		t.Fatalf("read --json error: %v", err)
-	}
-	var got struct {
-		Skill, Path, Content, Guidance string
-	}
-	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
-		t.Fatalf("invalid JSON: %v", e)
-	}
-	if got.Skill != "lark-calendar" || got.Path != "SKILL.md" || got.Content == "" {
-		t.Errorf("envelope: %+v", got)
-	}
-	// Guidance is a separate field, not merged into content.
-	if got.Guidance == "" {
-		t.Error("expected guidance field for main SKILL.md")
-	}
-	if strings.Contains(got.Content, "Tip:") {
-		t.Error("guidance must not be merged into content")
-	}
-}
-
-func TestSkillReadFile(t *testing.T) {
-	// Both the 2-arg and slash forms read the same file, with no guidance tip.
-	for _, args := range [][]string{
-		{"read", "lark-calendar", "references/agenda.md"},
-		{"read", "lark-calendar/references/agenda.md"},
-	} {
-		stdout, stderr, err := run(t, calFS(), args...)
-		if err != nil {
-			t.Fatalf("read %v error: %v", args, err)
-		}
-		if stdout != "# Agenda" {
-			t.Errorf("read %v output: got %q", args, stdout)
-		}
-		// Reference reads carry no guidance on either stream.
-		if strings.Contains(stderr, "Tip:") {
-			t.Errorf("read %v must not emit guidance on stderr: got %q", args, stderr)
-		}
-	}
-}
-
-func TestSkillReadFileJSON(t *testing.T) {
-	stdout, _, err := run(t, calFS(), "read", "lark-calendar", "references/agenda.md", "--json")
-	if err != nil {
-		t.Fatalf("read file --json error: %v", err)
-	}
-	var got struct {
-		Skill, Path, Content, Guidance string
-	}
-	if e := json.Unmarshal([]byte(stdout), &got); e != nil {
-		t.Fatalf("invalid JSON: %v\n%s", e, stdout)
-	}
-	if got.Skill != "lark-calendar" || got.Path != "references/agenda.md" || got.Content != "# Agenda" {
-		t.Errorf("envelope: %+v", got)
-	}
-	// Reference reads do not carry the guidance tip.
-	if got.Guidance != "" {
-		t.Errorf("reference read must not include guidance, got %q", got.Guidance)
-	}
-}
-
-func TestSkillReadUnknown(t *testing.T) {
-	_, _, err := run(t, calFS(), "read", "no-such")
-	if err == nil {
-		t.Fatal("expected error")
-	}
-	if !strings.Contains(err.Error(), "unknown skill") {
-		t.Errorf("err: %v", err)
-	}
-}
-
-func TestSkillReadMissingArg(t *testing.T) {
-	_, _, err := run(t, calFS(), "read")
-	if err == nil || !strings.Contains(err.Error(), "requires 1 or 2 arguments") {
-		t.Fatalf("expected arg error, got %v", err)
-	}
-}
-
-func TestSkillReadTraversal(t *testing.T) {
-	stdout, _, err := run(t, calFS(), "read", "lark-calendar", "../../etc/passwd")
-	if err == nil {
-		t.Fatal("expected rejection")
-	}
-	if !strings.Contains(err.Error(), "invalid path") {
-		t.Errorf("err: %v", err)
-	}
-	if stdout != "" {
-		t.Errorf("stdout must be empty on rejection, got %q", stdout)
-	}
-}
-
-func TestSkillNilContentFS(t *testing.T) {
-	_, _, err := run(t, nil, "list")
-	if err == nil {
-		t.Fatal("expected error when SkillContent is nil")
-	}
-	if !strings.Contains(err.Error(), "not embedded") {
-		t.Errorf("err: %v", err)
-	}
-}

cmd/update/update_test.go

@@ -49,21 +49,12 @@ func mockDetectAndNpm(t *testing.T, result selfupdate.DetectResult, npmFn func(s
 		u.DetectOverride = func() selfupdate.DetectResult { return result }
 		u.NpmInstallOverride = npmFn
 		u.VerifyOverride = func(string) error { return nil }
-		u.SkillsIndexFetchOverride = successfulSkillsIndexFetch()
 		u.SkillsCommandOverride = successfulSkillsCommand()
 		return u
 	}
 	t.Cleanup(func() { newUpdater = origNew })
 }
 
-func successfulSkillsIndexFetch() func() *selfupdate.NpmResult {
-	return func() *selfupdate.NpmResult {
-		r := &selfupdate.NpmResult{}
-		r.Stdout.WriteString(`{"skills":[{"name":"lark-calendar"},{"name":"lark-mail"}]}`)
-		return r
-	}
-}
-
 func successfulSkillsCommand() func(args ...string) *selfupdate.NpmResult {
 	return func(args ...string) *selfupdate.NpmResult {
 		r := &selfupdate.NpmResult{}
@@ -487,10 +478,6 @@ func TestUpdateNpmVerifyFail_JSON_NoRestoreHintWhenBackupUnavailable(t *testing.
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return errors.New("bad binary") }
 		u.RestoreAvailableOverride = func() bool { return false }
-		u.SkillsIndexFetchOverride = func() *selfupdate.NpmResult {
-			t.Fatal("skills sync should not run when binary verification fails")
-			return nil
-		}
 		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
 			t.Fatal("skills sync should not run when binary verification fails")
 			return nil
@@ -823,11 +810,6 @@ func TestUpdateNpm_SkillsFail_JSON(t *testing.T) {
 		}
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return nil }
-		u.SkillsIndexFetchOverride = func() *selfupdate.NpmResult {
-			r := &selfupdate.NpmResult{}
-			r.Err = fmt.Errorf("index unavailable")
-			return r
-		}
 		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
 			r := &selfupdate.NpmResult{}
 			r.Stderr.WriteString("npx: command not found")
@@ -880,11 +862,6 @@ func TestUpdateNpm_SkillsFail_Human(t *testing.T) {
 		}
 		u.NpmInstallOverride = func(version string) *selfupdate.NpmResult { return &selfupdate.NpmResult{} }
 		u.VerifyOverride = func(string) error { return nil }
-		u.SkillsIndexFetchOverride = func() *selfupdate.NpmResult {
-			r := &selfupdate.NpmResult{}
-			r.Err = fmt.Errorf("index unavailable")
-			return r
-		}
 		u.SkillsCommandOverride = func(args ...string) *selfupdate.NpmResult {
 			r := &selfupdate.NpmResult{}
 			r.Stderr.WriteString("npx: command not found")
@@ -1029,7 +1006,6 @@ func TestUpdateRun_AlreadyLatest_RunsSkillsSync(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
-			SkillsIndexFetchOverride: successfulSkillsIndexFetch(),
 			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
 				return successfulSkillsCommand()(args...)
@@ -1068,7 +1044,6 @@ func TestUpdateRun_Manual_RunsSkillsSync(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
-			SkillsIndexFetchOverride: successfulSkillsIndexFetch(),
 			DetectOverride: func() selfupdate.DetectResult {
 				return selfupdate.DetectResult{
 					Method:       selfupdate.InstallManual,
@@ -1113,7 +1088,6 @@ func TestUpdateRun_Npm_RunsSkillsSync_WritesLatestState(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
-			SkillsIndexFetchOverride: successfulSkillsIndexFetch(),
 			DetectOverride: func() selfupdate.DetectResult {
 				return selfupdate.DetectResult{
 					Method: selfupdate.InstallNpm, NpmAvailable: true,
@@ -1173,10 +1147,6 @@ func TestUpdateRun_CheckIncludesSkillsStatus(t *testing.T) {
 			DetectOverride: func() selfupdate.DetectResult {
 				return selfupdate.DetectResult{Method: selfupdate.InstallNpm, NpmAvailable: true}
 			},
-			SkillsIndexFetchOverride: func() *selfupdate.NpmResult {
-				skillsCalled = true
-				return successfulSkillsIndexFetch()()
-			},
 			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
 				return successfulSkillsCommand()(args...)
@@ -1226,10 +1196,6 @@ func TestUpdateRun_CheckAlreadyLatest_NoSideEffect(t *testing.T) {
 	t.Cleanup(func() { newUpdater = origNew })
 	newUpdater = func() *selfupdate.Updater {
 		return &selfupdate.Updater{
-			SkillsIndexFetchOverride: func() *selfupdate.NpmResult {
-				skillsCalled = true
-				return successfulSkillsIndexFetch()()
-			},
 			SkillsCommandOverride: func(args ...string) *selfupdate.NpmResult {
 				skillsCalled = true
 				return successfulSkillsCommand()(args...)

internal/cmdutil/factory.go

@@ -6,7 +6,6 @@ package cmdutil
 import (
 	"context"
 	"io"
-	"io/fs"
 	"net/http"
 	"strings"
 
@@ -44,8 +43,6 @@ type Factory struct {
 	Credential *credential.CredentialProvider
 
 	FileIOProvider fileio.Provider // file transfer provider (default: local filesystem)
-
-	SkillContent fs.FS // embedded skill tree (rooted at the skill list); nil when the build embeds no skills
 }
 
 // ResolveFileIO resolves a FileIO instance using the current execution context.

internal/errclass/codemeta_minutes.go

@@ -1,18 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errclass
-
-import "github.com/larksuite/cli/errs"
-
-// minutesCodeMeta holds minutes-service Lark code → CodeMeta mappings.
-// Only codes whose meaning is stable across minutes endpoints are registered;
-// endpoint-specific codes fall back to CategoryAPI via BuildAPIError.
-// Command-specific messages, hints, and subtypes are layered on top via
-// per-command enrichment.
-// BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
-var minutesCodeMeta = map[int]CodeMeta{
-	2091005: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied}, // caller lacks edit/read permission for the minute
-}
-
-func init() { mergeCodeMeta(minutesCodeMeta, "minutes") }

internal/errclass/codemeta_test.go

@@ -70,12 +70,6 @@ func TestLookupCodeMeta_TaskPermissionDenied_MergedViaInit(t *testing.T) {
 	}
 }
 
-func TestLookupCodeMeta_MinutesEndpointSpecificCode_NotGlobal(t *testing.T) {
-	if got, ok := LookupCodeMeta(2091001); ok {
-		t.Fatalf("LookupCodeMeta(2091001) = %+v, want unregistered; minutes endpoints use this code for different failures", got)
-	}
-}
-
 func TestLookupCodeMeta_RetryableAuthCode(t *testing.T) {
 	got, ok := LookupCodeMeta(20050)
 	if !ok {

internal/errclass/codemeta_vc.go

@@ -1,19 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package errclass
-
-import "github.com/larksuite/cli/errs"
-
-// vcCodeMeta holds vc-service Lark code → CodeMeta mappings.
-// Only codes whose meaning is verifiable from repo evidence are registered;
-// ambiguous codes (e.g. 124002 "recording still generating", which has no
-// precise taxonomy fit) fall back to CategoryAPI via BuildAPIError and rely on
-// per-command enrichment for a retry hint.
-// BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
-var vcCodeMeta = map[int]CodeMeta{
-	121004: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                   // meeting has no minute file
-	121005: {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied}, // caller is not a participant / lacks view permission
-}
-
-func init() { mergeCodeMeta(vcCodeMeta, "vc") }

internal/selfupdate/updater.go

@@ -10,13 +10,10 @@ import (
 	"bytes"
 	"context"
 	"fmt"
-	"io"
-	"net/http"
 	"os/exec"
 	"strings"
 	"time"
 
-	"github.com/larksuite/cli/internal/transport"
 	"github.com/larksuite/cli/internal/vfs"
 )
 
@@ -40,15 +37,9 @@ const (
 )
 
 const (
-	npmInstallTimeout      = 10 * time.Minute
-	skillsUpdateTimeout    = 2 * time.Minute
-	skillsIndexMaxBodySize = 1 << 20
-	verifyTimeout          = 10 * time.Second
-)
-
-var (
-	skillsIndexFetchTimeout = 10 * time.Second
-	officialSkillsIndexURL  = "https://open.feishu.cn/.well-known/skills/index.json"
+	npmInstallTimeout   = 10 * time.Minute
+	skillsUpdateTimeout = 2 * time.Minute
+	verifyTimeout       = 10 * time.Second
 )
 
 // DetectResult holds installation detection results.
@@ -92,7 +83,6 @@ func (r *NpmResult) CombinedOutput() string {
 type Updater struct {
 	DetectOverride           func() DetectResult
 	NpmInstallOverride       func(version string) *NpmResult
-	SkillsIndexFetchOverride func() *NpmResult
 	SkillsCommandOverride    func(args ...string) *NpmResult
 	VerifyOverride           func(expectedVersion string) error
 	RestoreAvailableOverride func() bool
@@ -163,53 +153,6 @@ func (u *Updater) RunNpmInstall(version string) *NpmResult {
 	return r
 }
 
-func (u *Updater) ListOfficialSkillsIndex() *NpmResult {
-	if u.SkillsIndexFetchOverride != nil {
-		return u.SkillsIndexFetchOverride()
-	}
-
-	r := &NpmResult{}
-	ctx, cancel := context.WithTimeout(context.Background(), skillsIndexFetchTimeout)
-	defer cancel()
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, officialSkillsIndexURL, nil)
-	if err != nil {
-		r.Err = err
-		return r
-	}
-
-	client := transport.NewHTTPClient(0)
-	client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
-		if req.URL.Scheme != "https" {
-			return fmt.Errorf("official skills index redirected to non-HTTPS URL: %s", req.URL.Redacted())
-		}
-		return nil
-	}
-	resp, err := client.Do(req)
-	if err != nil {
-		r.Err = err
-		return r
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices {
-		r.Err = fmt.Errorf("official skills index returned HTTP %d", resp.StatusCode)
-		return r
-	}
-
-	limited := io.LimitReader(resp.Body, skillsIndexMaxBodySize+1)
-	if _, err := io.Copy(&r.Stdout, limited); err != nil {
-		r.Err = err
-		return r
-	}
-	if r.Stdout.Len() > skillsIndexMaxBodySize {
-		r.Stdout.Reset()
-		r.Err = fmt.Errorf("official skills index exceeds %d bytes", skillsIndexMaxBodySize)
-		return r
-	}
-	return r
-}
-
 func (u *Updater) ListOfficialSkills() *NpmResult {
 	r := u.runSkillsListOfficial("https://open.feishu.cn")
 	if r.Err != nil {

internal/selfupdate/updater_test.go

@@ -4,18 +4,12 @@
 package selfupdate
 
 import (
-	"context"
-	"errors"
 	"fmt"
-	"net"
-	"net/http"
-	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"runtime"
 	"strings"
 	"testing"
-	"time"
 
 	"github.com/larksuite/cli/internal/vfs"
 )
@@ -238,113 +232,6 @@ func TestSkillsCommandsUseExpectedArgs(t *testing.T) {
 	}
 }
 
-func TestListOfficialSkillsIndexSuccess(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		fmt.Fprint(w, `{"skills":[{"name":"lark-calendar"}]}`)
-	}))
-	defer server.Close()
-
-	oldURL := officialSkillsIndexURL
-	officialSkillsIndexURL = server.URL
-	t.Cleanup(func() { officialSkillsIndexURL = oldURL })
-
-	result := New().ListOfficialSkillsIndex()
-	if result.Err != nil {
-		t.Fatalf("ListOfficialSkillsIndex() err = %v, want nil", result.Err)
-	}
-	if got := result.Stdout.String(); !strings.Contains(got, "lark-calendar") {
-		t.Fatalf("ListOfficialSkillsIndex() stdout = %q, want skill JSON", got)
-	}
-}
-
-func TestListOfficialSkillsIndexHTTPError(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		http.Error(w, "not found", http.StatusNotFound)
-	}))
-	defer server.Close()
-
-	oldURL := officialSkillsIndexURL
-	officialSkillsIndexURL = server.URL
-	t.Cleanup(func() { officialSkillsIndexURL = oldURL })
-
-	result := New().ListOfficialSkillsIndex()
-	if result.Err == nil || !strings.Contains(result.Err.Error(), "HTTP 404") {
-		t.Fatalf("ListOfficialSkillsIndex() err = %v, want HTTP 404", result.Err)
-	}
-}
-
-func TestListOfficialSkillsIndexBodyTooLarge(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		fmt.Fprint(w, strings.Repeat("x", skillsIndexMaxBodySize+1))
-	}))
-	defer server.Close()
-
-	oldURL := officialSkillsIndexURL
-	officialSkillsIndexURL = server.URL
-	t.Cleanup(func() { officialSkillsIndexURL = oldURL })
-
-	result := New().ListOfficialSkillsIndex()
-	if result.Err == nil || !strings.Contains(result.Err.Error(), "exceeds") {
-		t.Fatalf("ListOfficialSkillsIndex() err = %v, want exceeds", result.Err)
-	}
-	if result.Stdout.Len() != 0 {
-		t.Fatalf("ListOfficialSkillsIndex() stdout len = %d, want 0", result.Stdout.Len())
-	}
-}
-
-func TestListOfficialSkillsIndexTimeout(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		time.Sleep(200 * time.Millisecond)
-		fmt.Fprint(w, `{"skills":[{"name":"lark-calendar"}]}`)
-	}))
-	defer server.Close()
-
-	oldURL := officialSkillsIndexURL
-	oldTimeout := skillsIndexFetchTimeout
-	officialSkillsIndexURL = server.URL
-	skillsIndexFetchTimeout = 50 * time.Millisecond
-	t.Cleanup(func() {
-		officialSkillsIndexURL = oldURL
-		skillsIndexFetchTimeout = oldTimeout
-	})
-
-	result := New().ListOfficialSkillsIndex()
-	var netErr net.Error
-	if result.Err == nil || (!errors.Is(result.Err, context.DeadlineExceeded) && !(errors.As(result.Err, &netErr) && netErr.Timeout())) {
-		t.Fatalf("ListOfficialSkillsIndex() err = %v, want timeout error", result.Err)
-	}
-}
-
-func TestListOfficialSkillsIndexRejectsNonHTTPSRedirect(t *testing.T) {
-	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		http.Redirect(w, r, "http://example.com/skills.json", http.StatusFound)
-	}))
-	defer server.Close()
-
-	oldURL := officialSkillsIndexURL
-	officialSkillsIndexURL = server.URL
-	t.Cleanup(func() { officialSkillsIndexURL = oldURL })
-
-	result := New().ListOfficialSkillsIndex()
-	if result.Err == nil || !strings.Contains(result.Err.Error(), "non-HTTPS") {
-		t.Fatalf("ListOfficialSkillsIndex() err = %v, want non-HTTPS redirect", result.Err)
-	}
-}
-
-func TestListOfficialSkillsIndexUsesOverride(t *testing.T) {
-	result := (&Updater{SkillsIndexFetchOverride: func() *NpmResult {
-		r := &NpmResult{}
-		r.Stdout.WriteString(`{"skills":[{"name":"override-skill"}]}`)
-		return r
-	}}).ListOfficialSkillsIndex()
-	if result.Err != nil {
-		t.Fatalf("ListOfficialSkillsIndex() err = %v, want nil", result.Err)
-	}
-	if !strings.Contains(result.Stdout.String(), "override-skill") {
-		t.Fatalf("ListOfficialSkillsIndex() stdout = %q, want override result", result.Stdout.String())
-	}
-}
-
 func TestListOfficialSkillsFallsBack(t *testing.T) {
 	called := []string{}
 	updater := &Updater{

internal/skillcontent/reader.go

@@ -1,209 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package skillcontent reads embedded skill content from an injected fs.FS
-// rooted at the skill list (entries like "lark-calendar/SKILL.md").
-package skillcontent
-
-import (
-	"io/fs"
-	"path"
-	"sort"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-	"gopkg.in/yaml.v3"
-)
-
-type Reader struct {
-	fsys fs.FS
-}
-
-func New(fsys fs.FS) *Reader { return &Reader{fsys: fsys} }
-
-type SkillInfo struct {
-	Name        string         `json:"name"`
-	Description string         `json:"description"`
-	Version     string         `json:"version,omitempty"`
-	Metadata    map[string]any `json:"metadata,omitempty"`
-}
-
-// DirEntry.Path is skill-prefixed (e.g. "lark-doc/references/x.md") so it can be
-// fed straight back into `read`.
-type DirEntry struct {
-	Path  string `json:"path"`
-	IsDir bool   `json:"is_dir"`
-}
-
-func (r *Reader) List() ([]SkillInfo, error) {
-	entries, err := fs.ReadDir(r.fsys, ".")
-	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeFileIO, "failed to read embedded skills: %v", err)
-	}
-	out := make([]SkillInfo, 0, len(entries))
-	for _, e := range entries {
-		if !e.IsDir() {
-			continue
-		}
-		// Skip dirs that aren't real skills (no SKILL.md).
-		if info, ok := r.skillInfo(e.Name()); ok {
-			out = append(out, info)
-		}
-	}
-	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
-	return out, nil
-}
-
-func (r *Reader) skillInfo(name string) (SkillInfo, bool) {
-	data, err := fs.ReadFile(r.fsys, name+"/SKILL.md")
-	if err != nil {
-		return SkillInfo{}, false
-	}
-	desc, version, metadata := parseFrontmatter(data)
-	return SkillInfo{Name: name, Description: desc, Version: version, Metadata: metadata}, true
-}
-
-// ListPath lists one directory layer (no recursion) under "<name>" or
-// "<name>/<sub>", returning the entries and the cleaned path listed.
-func (r *Reader) ListPath(arg string) ([]DirEntry, string, error) {
-	name, sub := SplitArg(arg)
-	if err := r.ensureSkill(name); err != nil {
-		return nil, "", err
-	}
-	dir := name
-	if sub != "" {
-		cleaned, err := cleanSubPath(sub)
-		if err != nil {
-			return nil, "", err
-		}
-		dir = name + "/" + cleaned
-		info, err := fs.Stat(r.fsys, dir)
-		if err != nil {
-			return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"path %q not found in skill %q", sub, name).
-				WithHint("run 'lark-cli skills list " + name + "' to see files in this skill")
-		}
-		if !info.IsDir() {
-			return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"path %q is a file, not a directory; use 'lark-cli skills read %s/%s' to read it", sub, name, cleaned)
-		}
-	}
-	entries, err := fs.ReadDir(r.fsys, dir)
-	if err != nil {
-		return nil, "", errs.NewInternalError(errs.SubtypeFileIO,
-			"failed to read embedded skill content: %v", err)
-	}
-	out := make([]DirEntry, 0, len(entries))
-	for _, e := range entries {
-		out = append(out, DirEntry{Path: dir + "/" + e.Name(), IsDir: e.IsDir()})
-	}
-	sort.Slice(out, func(i, j int) bool { return out[i].Path < out[j].Path })
-	return out, dir, nil
-}
-
-// SplitArg splits "<name>/<rest>" at the first separator; an argument with no
-// separator is a bare skill name (rest "").
-func SplitArg(arg string) (name, rest string) {
-	name, rest, _ = strings.Cut(arg, "/")
-	return name, rest
-}
-
-// parseFrontmatter best-effort-extracts the frontmatter fields; missing or
-// unparseable frontmatter yields ("", "", nil), never an error.
-func parseFrontmatter(skillMD []byte) (description, version string, metadata map[string]any) {
-	lines := strings.Split(string(skillMD), "\n")
-	if strings.TrimRight(lines[0], "\r") != "---" {
-		return "", "", nil
-	}
-	block := make([]string, 0, len(lines))
-	closed := false
-	for _, ln := range lines[1:] {
-		if strings.TrimRight(ln, "\r") == "---" {
-			closed = true
-			break
-		}
-		block = append(block, ln)
-	}
-	if !closed {
-		return "", "", nil
-	}
-	var fm struct {
-		Description string         `yaml:"description"`
-		Version     string         `yaml:"version"`
-		Metadata    map[string]any `yaml:"metadata"`
-	}
-	if err := yaml.Unmarshal([]byte(strings.Join(block, "\n")), &fm); err != nil {
-		return "", "", nil
-	}
-	return fm.Description, fm.Version, fm.Metadata
-}
-
-func (r *Reader) ReadSkill(name string) ([]byte, error) {
-	if err := r.ensureSkill(name); err != nil {
-		return nil, err
-	}
-	data, err := fs.ReadFile(r.fsys, name+"/SKILL.md")
-	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeFileIO,
-			"failed to read embedded skill content: %v", err)
-	}
-	return data, nil
-}
-
-func (r *Reader) ensureSkill(name string) error {
-	if name == "" || strings.ContainsAny(name, `/\`) || name == "." || name == ".." {
-		return unknownSkill(name)
-	}
-	info, err := fs.Stat(r.fsys, name)
-	if err != nil || !info.IsDir() {
-		return unknownSkill(name)
-	}
-	return nil
-}
-
-func unknownSkill(name string) error {
-	return errs.NewValidationError(errs.SubtypeInvalidArgument, "unknown skill %q", name).
-		WithHint("run 'lark-cli skills list' to see available skills")
-}
-
-// cleanSubPath returns the cleaned form of relpath, rejecting absolute paths and
-// ".." escapes. relpath must be non-empty (callers handle the skill-root case).
-func cleanSubPath(relpath string) (string, error) {
-	cleaned := path.Clean(relpath)
-	// path.Clean only treats '/' as a separator, so a Windows-style "..\" prefix
-	// survives; reject it explicitly alongside "../".
-	if relpath == "" || path.IsAbs(relpath) || cleaned == "." ||
-		cleaned == ".." || strings.HasPrefix(cleaned, "../") || strings.HasPrefix(cleaned, `..\`) {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"invalid path %q: must be a relative path without '..'", relpath)
-	}
-	return cleaned, nil
-}
-
-// ReadReference returns the bytes of <name>/<relpath> and the cleaned path.
-func (r *Reader) ReadReference(name, relpath string) ([]byte, string, error) {
-	if err := r.ensureSkill(name); err != nil {
-		return nil, "", err
-	}
-	cleaned, err := cleanSubPath(relpath)
-	if err != nil {
-		return nil, "", err
-	}
-	full := name + "/" + cleaned
-	info, err := fs.Stat(r.fsys, full)
-	if err != nil {
-		return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"reference %q not found in skill %q", relpath, name).
-			WithHint("run 'lark-cli skills list " + name + "' to see files in this skill")
-	}
-	if info.IsDir() {
-		return nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"reference %q is a directory, not a file", relpath)
-	}
-	data, err := fs.ReadFile(r.fsys, full)
-	if err != nil {
-		return nil, "", errs.NewInternalError(errs.SubtypeFileIO,
-			"failed to read embedded skill content: %v", err)
-	}
-	return data, cleaned, nil
-}

internal/skillcontent/reader_test.go

@@ -1,290 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package skillcontent
-
-import (
-	"errors"
-	"strings"
-	"testing"
-	"testing/fstest"
-
-	"github.com/larksuite/cli/errs"
-)
-
-func testFS() fstest.MapFS {
-	return fstest.MapFS{
-		"lark-calendar/SKILL.md":             {Data: []byte("---\nname: lark-calendar\nversion: 1.0.0\ndescription: \"Calendar skill\"\nmetadata:\n  requires:\n    bins: [\"lark-cli\"]\n  cliHelp: \"lark-cli calendar --help\"\n---\nbody\n")},
-		"lark-calendar/references/agenda.md": {Data: []byte("# Agenda")},
-		"lark-calendar/references/create.md": {Data: []byte("# Create")},
-		"lark-calendar/assets/tpl.html":      {Data: []byte("<html></html>")},
-		"lark-im/SKILL.md":                   {Data: []byte("no frontmatter here\n")},
-		"lark-im/references/send.md":         {Data: []byte("# Send")},
-	}
-}
-
-func TestList(t *testing.T) {
-	r := New(testFS())
-	skills, err := r.List()
-	if err != nil {
-		t.Fatalf("List() error: %v", err)
-	}
-	if len(skills) != 2 {
-		t.Fatalf("got %d skills, want 2", len(skills))
-	}
-	if skills[0].Name != "lark-calendar" || skills[1].Name != "lark-im" {
-		t.Fatalf("skills not sorted by name: %v", skills)
-	}
-	if skills[0].Description != "Calendar skill" {
-		t.Errorf("description: got %q, want %q", skills[0].Description, "Calendar skill")
-	}
-	// version is the frontmatter `version:` field, passed through for drift checks.
-	if skills[0].Version != "1.0.0" {
-		t.Errorf("version: got %q, want %q", skills[0].Version, "1.0.0")
-	}
-	// metadata is the frontmatter `metadata:` block, passed through verbatim.
-	if skills[0].Metadata == nil {
-		t.Fatal("expected metadata for lark-calendar")
-	}
-	if skills[0].Metadata["cliHelp"] != "lark-cli calendar --help" {
-		t.Errorf("metadata.cliHelp: got %v", skills[0].Metadata["cliHelp"])
-	}
-	// No frontmatter → empty description and nil metadata (omitted from JSON).
-	if skills[1].Description != "" {
-		t.Errorf("lark-im description: got %q, want empty", skills[1].Description)
-	}
-	if skills[1].Metadata != nil {
-		t.Errorf("lark-im metadata: got %v, want nil", skills[1].Metadata)
-	}
-	if skills[1].Version != "" {
-		t.Errorf("lark-im version: got %q, want empty", skills[1].Version)
-	}
-}
-
-func TestListPath(t *testing.T) {
-	r := New(testFS())
-
-	// Skill root: direct children only (one layer), each path skill-prefixed.
-	entries, listed, err := r.ListPath("lark-calendar")
-	if err != nil {
-		t.Fatalf("ListPath root error: %v", err)
-	}
-	if listed != "lark-calendar" {
-		t.Errorf("listed path: got %q", listed)
-	}
-	want := map[string]bool{ // path → isDir
-		"lark-calendar/SKILL.md":   false,
-		"lark-calendar/references": true,
-		"lark-calendar/assets":     true,
-	}
-	if len(entries) != len(want) {
-		t.Fatalf("root entries: got %v, want %d entries", entries, len(want))
-	}
-	for _, e := range entries {
-		isDir, ok := want[e.Path]
-		if !ok {
-			t.Errorf("unexpected entry %q", e.Path)
-			continue
-		}
-		if e.IsDir != isDir {
-			t.Errorf("%q is_dir: got %v, want %v", e.Path, e.IsDir, isDir)
-		}
-	}
-	// Entries are sorted by path.
-	if entries[0].Path != "lark-calendar/SKILL.md" {
-		t.Errorf("entries not sorted: %v", entries)
-	}
-
-	// Subdirectory: one layer under <name>/<subpath>.
-	subEntries, subListed, err := r.ListPath("lark-calendar/references")
-	if err != nil {
-		t.Fatalf("ListPath subdir error: %v", err)
-	}
-	if subListed != "lark-calendar/references" {
-		t.Errorf("listed subpath: got %q", subListed)
-	}
-	if len(subEntries) != 2 ||
-		subEntries[0].Path != "lark-calendar/references/agenda.md" ||
-		subEntries[1].Path != "lark-calendar/references/create.md" {
-		t.Errorf("subdir entries: got %v", subEntries)
-	}
-
-	// Unknown skill → typed validation error.
-	if _, _, err := r.ListPath("no-such-skill"); err == nil {
-		t.Error("expected error for unknown skill")
-	} else {
-		var verr *errs.ValidationError
-		if !errors.As(err, &verr) {
-			t.Errorf("expected *errs.ValidationError, got %T", err)
-		}
-	}
-
-	// Path that points at a file (not a dir) → validation error.
-	if _, _, err := r.ListPath("lark-calendar/SKILL.md"); err == nil {
-		t.Error("expected error listing a file")
-	} else if !strings.Contains(err.Error(), "is a file") {
-		t.Errorf("message: got %q", err.Error())
-	}
-
-	// Nonexistent subpath → validation error.
-	if _, _, err := r.ListPath("lark-calendar/nope"); err == nil {
-		t.Error("expected not-found error")
-	} else if !strings.Contains(err.Error(), "not found") {
-		t.Errorf("message: got %q", err.Error())
-	}
-
-	// Traversal in the subpath is rejected, no listing leaked.
-	for _, bad := range []string{"lark-calendar/../lark-im", "lark-calendar/../../etc", `lark-calendar/..\x`} {
-		entries, _, err := r.ListPath(bad)
-		if err == nil {
-			t.Errorf("expected rejection for %q", bad)
-		}
-		if entries != nil {
-			t.Errorf("entries leaked for %q: %v", bad, entries)
-		}
-	}
-}
-
-func TestReadSkill(t *testing.T) {
-	r := New(testFS())
-
-	data, err := r.ReadSkill("lark-calendar")
-	if err != nil {
-		t.Fatalf("ReadSkill error: %v", err)
-	}
-	if !strings.HasPrefix(string(data), "---\nname: lark-calendar") {
-		t.Errorf("unexpected content: %q", string(data))
-	}
-
-	_, err = r.ReadSkill("no-such-skill")
-	if err == nil {
-		t.Fatal("expected error for unknown skill")
-	}
-	var verr *errs.ValidationError
-	if !errors.As(err, &verr) {
-		t.Fatalf("expected *errs.ValidationError, got %T", err)
-	}
-	if !strings.Contains(verr.Message, `unknown skill "no-such-skill"`) {
-		t.Errorf("message: got %q", verr.Message)
-	}
-
-	if _, err := r.ReadSkill("../etc"); err == nil {
-		t.Error("expected error for name with separator")
-	}
-}
-
-func TestReadReference(t *testing.T) {
-	r := New(testFS())
-
-	data, cleaned, err := r.ReadReference("lark-calendar", "references/agenda.md")
-	if err != nil {
-		t.Fatalf("ReadReference error: %v", err)
-	}
-	if string(data) != "# Agenda" {
-		t.Errorf("content: got %q", string(data))
-	}
-	if cleaned != "references/agenda.md" {
-		t.Errorf("cleaned path: got %q", cleaned)
-	}
-
-	if _, _, err := r.ReadReference("lark-calendar", "references/nope.md"); err == nil {
-		t.Error("expected not-found error")
-	} else if !strings.Contains(err.Error(), "not found") {
-		t.Errorf("message: got %q", err.Error())
-	}
-
-	if _, _, err := r.ReadReference("lark-calendar", "references"); err == nil {
-		t.Error("expected directory error")
-	} else if !strings.Contains(err.Error(), "is a directory") {
-		t.Errorf("message: got %q", err.Error())
-	}
-
-	for _, bad := range []string{"../../etc/passwd", "/etc/passwd", "..", "", "references/../../im/SKILL.md", `..\..\x`} {
-		data, _, err := r.ReadReference("lark-calendar", bad)
-		if err == nil {
-			t.Errorf("expected rejection for %q", bad)
-		}
-		if data != nil {
-			t.Errorf("content leaked for %q: %q", bad, string(data))
-		}
-		var verr *errs.ValidationError
-		if !errors.As(err, &verr) {
-			t.Errorf("expected validation error for %q, got %T", bad, err)
-		}
-	}
-}
-
-func TestParseFrontmatter(t *testing.T) {
-	cases := []struct {
-		name        string
-		input       string
-		wantDesc    string
-		wantVer     string
-		wantHasMeta bool
-	}{
-		{
-			name:        "description, version and metadata",
-			input:       "---\ndescription: My skill\nversion: 2.1.0\nmetadata:\n  cliHelp: \"x\"\n---\nbody\n",
-			wantDesc:    "My skill",
-			wantVer:     "2.1.0",
-			wantHasMeta: true,
-		},
-		{
-			name:     "description only, no metadata",
-			input:    "---\ndescription: Plain\n---\nbody\n",
-			wantDesc: "Plain",
-		},
-		{
-			name:  "no frontmatter",
-			input: "no frontmatter here\n",
-		},
-		{
-			name:  "unclosed frontmatter",
-			input: "---\ndescription: Never closed\n",
-		},
-		{
-			name:  "malformed YAML inside frontmatter",
-			input: "---\n: bad: yaml: [\n---\nbody\n",
-		},
-		{
-			name:        "CRLF line endings",
-			input:       "---\r\ndescription: CRLF skill\r\nmetadata:\r\n  cliHelp: \"y\"\r\n---\r\nbody\r\n",
-			wantDesc:    "CRLF skill",
-			wantHasMeta: true,
-		},
-		{
-			name:  "empty input",
-			input: "",
-		},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			desc, ver, meta := parseFrontmatter([]byte(tc.input))
-			if desc != tc.wantDesc {
-				t.Errorf("description = %q, want %q", desc, tc.wantDesc)
-			}
-			if ver != tc.wantVer {
-				t.Errorf("version = %q, want %q", ver, tc.wantVer)
-			}
-			if (meta != nil) != tc.wantHasMeta {
-				t.Errorf("metadata = %v, wantHasMeta %v", meta, tc.wantHasMeta)
-			}
-		})
-	}
-}
-
-func TestReadSkillMissingFile(t *testing.T) {
-	// Use a separate MapFS so testFS() (and TestList) are unaffected.
-	emptyFS := fstest.MapFS{
-		"lark-empty/references/x.md": {Data: []byte("# X")},
-	}
-	r := New(emptyFS)
-	_, err := r.ReadSkill("lark-empty")
-	if err == nil {
-		t.Fatal("expected error when SKILL.md is absent")
-	}
-	var ierr *errs.InternalError
-	if !errors.As(err, &ierr) {
-		t.Fatalf("expected *errs.InternalError, got %T: %v", err, err)
-	}
-}

internal/skillscheck/sync.go

@@ -80,30 +80,6 @@ func ParseGlobalSkillsJSON(text string) []string {
 	return sortedKeys(seen)
 }
 
-func ParseOfficialSkillsIndexJSON(text string) ([]string, error) {
-	type officialSkill struct {
-		Name string `json:"name"`
-	}
-	type officialIndex struct {
-		Skills []officialSkill `json:"skills"`
-	}
-
-	var index officialIndex
-	if err := json.Unmarshal([]byte(text), &index); err != nil {
-		return nil, err
-	}
-
-	seen := map[string]bool{}
-	for _, skill := range index.Skills {
-		candidate := strings.TrimSpace(skill.Name)
-		if skillNamePattern.MatchString(candidate) {
-			seen[candidate] = true
-		}
-	}
-
-	return sortedKeys(seen), nil
-}
-
 // parseGlobalSkillsList parses the output of "npx -y skills ls -g"
 func parseGlobalSkillsList(lines []string) []string {
 	seen := map[string]bool{}
@@ -184,7 +160,8 @@ func parseOfficialSkillsList(lines []string) []string {
 
 			if len(parts) > 0 {
 				candidate := parts[0]
-				if skillNamePattern.MatchString(candidate) {
+				// Check if it's a valid official skill name
+				if strings.HasPrefix(candidate, "lark-") && skillNamePattern.MatchString(candidate) {
 					seen[candidate] = true
 				}
 			}
@@ -246,7 +223,6 @@ func PlanSync(input SyncInput) SyncPlan {
 }
 
 type SkillsRunner interface {
-	ListOfficialSkillsIndex() *selfupdate.NpmResult
 	ListOfficialSkills() *selfupdate.NpmResult
 	ListGlobalSkillsJSON() *selfupdate.NpmResult
 	ListGlobalSkills() *selfupdate.NpmResult
@@ -282,9 +258,14 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	}
 
 	// --- Step 1: List official skills ---
-	official, reason, ok := listOfficialSkills(opts.Runner)
-	if !ok {
-		return fallbackFullInstall(opts, reason, nil)
+	officialResult := opts.Runner.ListOfficialSkills()
+	if officialResult == nil || officialResult.Err != nil {
+		return fallbackFullInstall(opts, resultDetail(officialResult), nil)
+	}
+	official := ParseSkillsList(officialResult.Stdout.String())
+
+	if len(official) == 0 && strings.TrimSpace(officialResult.Stdout.String()) != "" {
+		return fallbackFullInstall(opts, "official skills list parsed as empty despite non-empty stdout", nil)
 	}
 
 	// --- Step 2: List local (installed) skills ---
@@ -346,40 +327,6 @@ func SyncSkills(opts SyncOptions) *SyncResult {
 	return result
 }
 
-func listOfficialSkills(runner SkillsRunner) ([]string, string, bool) {
-	reasons := []string{}
-
-	indexResult := runner.ListOfficialSkillsIndex()
-	if indexResult == nil || indexResult.Err != nil {
-		reasons = append(reasons, "official skills index failed: "+resultDetail(indexResult))
-	} else {
-		official, err := ParseOfficialSkillsIndexJSON(indexResult.Stdout.String())
-		if err != nil {
-			reasons = append(reasons, "official skills index JSON invalid: "+err.Error())
-		} else if len(official) > 0 {
-			return official, "", true
-		} else {
-			reasons = append(reasons, "official skills index contains no skills")
-		}
-	}
-
-	officialResult := runner.ListOfficialSkills()
-	if officialResult == nil || officialResult.Err != nil {
-		reasons = append(reasons, "official skills list failed: "+resultDetail(officialResult))
-		return nil, strings.Join(reasons, "; "), false
-	}
-	official := ParseSkillsList(officialResult.Stdout.String())
-	if len(official) > 0 {
-		return official, "", true
-	}
-	if strings.TrimSpace(officialResult.Stdout.String()) != "" {
-		reasons = append(reasons, "official skills list parsed as empty despite non-empty stdout")
-	} else {
-		reasons = append(reasons, "official skills list returned no skills")
-	}
-	return nil, strings.Join(reasons, "; "), false
-}
-
 func listLocalSkills(runner SkillsRunner) ([]string, bool) {
 	jsonResult := runner.ListGlobalSkillsJSON()
 	if jsonResult != nil && jsonResult.Err == nil {

internal/skillscheck/sync_test.go

@@ -30,19 +30,6 @@ lark-cli-harness:dev@0.1.0
 	}
 }
 
-func TestParseOfficialSkillsListAcceptsNonLarkOfficialNames(t *testing.T) {
-	input := `Available Skills
-│    lark-calendar
-│    official-shared
-│    bad/name
-`
-	got := ParseSkillsList(input)
-	want := []string{"lark-calendar", "official-shared"}
-	if !reflect.DeepEqual(got, want) {
-		t.Fatalf("ParseSkillsList() (Available Skills) = %#v, want %#v", got, want)
-	}
-}
-
 func TestParseGlobalSkillsList(t *testing.T) {
 	input := `Global Skills
 
@@ -123,43 +110,6 @@ func TestParseGlobalSkillsJSONInvalidOrUnsupported(t *testing.T) {
 	}
 }
 
-func TestParseOfficialSkillsIndexJSON(t *testing.T) {
-	input := `{
-  "skills": [
-    {"name":"lark-calendar","description":"Calendar","files":["SKILL.md"]},
-    {"name":"lark-mail","description":"Mail","files":["SKILL.md","references/lark-mail-search.md"]},
-    {"name":"  lark-base  ","description":"Base","files":[]},
-    {"name":"lark-calendar","description":"duplicate","files":["SKILL.md"]},
-    {"name":"custom-skill","description":"not official","files":["SKILL.md"]},
-    {"name":"bad skill","description":"invalid","files":["SKILL.md"]},
-    {"name":"","description":"empty","files":["SKILL.md"]}
-  ]
-}`
-	got, err := ParseOfficialSkillsIndexJSON(input)
-	if err != nil {
-		t.Fatalf("ParseOfficialSkillsIndexJSON() err = %v, want nil", err)
-	}
-	want := []string{"custom-skill", "lark-base", "lark-calendar", "lark-mail"}
-	if !reflect.DeepEqual(got, want) {
-		t.Fatalf("ParseOfficialSkillsIndexJSON() = %#v, want %#v", got, want)
-	}
-}
-
-func TestParseOfficialSkillsIndexJSONInvalidOrUnsupported(t *testing.T) {
-	for _, input := range []string{
-		`not json`,
-		`[{"name":"lark-calendar"}]`,
-		`{"name":"lark-calendar"}`,
-		`{"skills":[]}`,
-		`{"skills":[{"name":"bad skill"}]}`,
-	} {
-		got, err := ParseOfficialSkillsIndexJSON(input)
-		if err == nil && len(got) != 0 {
-			t.Fatalf("ParseOfficialSkillsIndexJSON(%q) = %#v, want empty", input, got)
-		}
-	}
-}
-
 func TestPlanNormal_WithReadableStatePreservesDeletedAndAddsNew(t *testing.T) {
 	previous := &SkillsState{OfficialSkills: []string{"lark-calendar", "lark-mail"}}
 	got := PlanSync(SyncInput{
@@ -206,11 +156,9 @@ func TestPlanForceRestoresAllOfficial(t *testing.T) {
 }
 
 type fakeSkillsRunner struct {
-	officialIndexOut string
 	officialOut      string
 	globalJSONOut    string
 	globalOut        string
-	officialIndexErr error
 	officialErr      error
 	globalJSONErr    error
 	globalErr        error
@@ -218,8 +166,6 @@ type fakeSkillsRunner struct {
 	installAllErr    error
 	installed        [][]string
 	installedAll     int
-	listedIndex      int
-	listedOfficial   int
 	listedGlobalJSON int
 	listedGlobalText int
 }
@@ -235,19 +181,6 @@ func officialSkillsOutput(names ...string) string {
 	return b.String()
 }
 
-func officialSkillsIndexOutput(names ...string) string {
-	var b strings.Builder
-	b.WriteString(`{"skills":[`)
-	for i, name := range names {
-		if i > 0 {
-			b.WriteString(",")
-		}
-		fmt.Fprintf(&b, `{"name":%q,"description":"test skill","files":["SKILL.md"]}`, name)
-	}
-	b.WriteString(`]}`)
-	return b.String()
-}
-
 func globalSkillsOutput(names ...string) string {
 	var b strings.Builder
 	b.WriteString("Global Skills\n\n")
@@ -273,16 +206,7 @@ func globalSkillsJSONOutput(names ...string) string {
 	return b.String()
 }
 
-func (f *fakeSkillsRunner) ListOfficialSkillsIndex() *selfupdate.NpmResult {
-	f.listedIndex++
-	r := &selfupdate.NpmResult{}
-	r.Stdout.WriteString(f.officialIndexOut)
-	r.Err = f.officialIndexErr
-	return r
-}
-
 func (f *fakeSkillsRunner) ListOfficialSkills() *selfupdate.NpmResult {
-	f.listedOfficial++
 	r := &selfupdate.NpmResult{}
 	r.Stdout.WriteString(f.officialOut)
 	r.Err = f.officialErr
@@ -331,10 +255,9 @@ func TestSyncSkills_WritesStateAndDoesNotWriteStamp(t *testing.T) {
 	}
 
 	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail", "lark-new"),
-		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail", "lark-new"),
-		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-custom"),
-		globalOut:        globalSkillsOutput("lark-mail"),
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail", "lark-new"),
+		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-custom"),
+		globalOut:     globalSkillsOutput("lark-mail"),
 	}
 	result := SyncSkills(SyncOptions{
 		Version: "1.0.33",
@@ -366,119 +289,12 @@ func TestSyncSkills_WritesStateAndDoesNotWriteStamp(t *testing.T) {
 	}
 }
 
-func TestSyncSkills_OfficialIndexSuccessSkipsOfficialListCommand(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail", "lark-new"),
-		officialOut:      officialSkillsOutput("lark-should-not-be-used"),
-		globalJSONOut:    globalSkillsJSONOutput("lark-calendar"),
-		globalOut:        globalSkillsOutput("lark-mail"),
-	}
-
-	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
-	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
-	}
-	assertStrings(t, result.Official, []string{"lark-calendar", "lark-mail", "lark-new"})
-	assertStrings(t, runner.installed[0], []string{"lark-calendar", "lark-mail", "lark-new"})
-	if runner.listedIndex != 1 {
-		t.Fatalf("listedIndex = %d, want 1", runner.listedIndex)
-	}
-	if runner.listedOfficial != 0 {
-		t.Fatalf("listedOfficial = %d, want 0 when index succeeds", runner.listedOfficial)
-	}
-}
-
-func TestSyncSkills_OfficialIndexFailureFallsBackToOfficialList(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	runner := &fakeSkillsRunner{
-		officialIndexErr: fmt.Errorf("index unavailable"),
-		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONOut:    globalSkillsJSONOutput("lark-calendar"),
-	}
-
-	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
-	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
-	}
-	assertStrings(t, result.Official, []string{"lark-calendar", "lark-mail"})
-	if runner.listedIndex != 1 || runner.listedOfficial != 1 {
-		t.Fatalf("listed index/official = %d/%d, want 1/1", runner.listedIndex, runner.listedOfficial)
-	}
-	if runner.installedAll != 0 {
-		t.Fatalf("installedAll = %d, want 0", runner.installedAll)
-	}
-}
-
-func TestSyncSkills_OfficialIndexEmptyFallsBackToOfficialList(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	runner := &fakeSkillsRunner{
-		officialIndexOut: `{"skills":[]}`,
-		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONOut:    globalSkillsJSONOutput("lark-calendar"),
-	}
-
-	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
-	if result.Err != nil {
-		t.Fatalf("SyncSkills() err = %v, want nil", result.Err)
-	}
-	assertStrings(t, result.Official, []string{"lark-calendar", "lark-mail"})
-	if runner.listedIndex != 1 || runner.listedOfficial != 1 {
-		t.Fatalf("listed index/official = %d/%d, want 1/1", runner.listedIndex, runner.listedOfficial)
-	}
-}
-
-func TestSyncSkills_OfficialDiscoveryFailuresFallBackToFullInstallWithReasons(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	runner := &fakeSkillsRunner{
-		officialIndexErr: fmt.Errorf("index unavailable"),
-		officialErr:      fmt.Errorf("list failed"),
-		installAllErr:    nil,
-	}
-
-	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
-	if result.Action != "fallback_synced" {
-		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
-	}
-	if runner.installedAll != 1 {
-		t.Fatalf("installedAll = %d, want 1", runner.installedAll)
-	}
-	if !strings.Contains(result.Detail, "official skills index failed") || !strings.Contains(result.Detail, "official skills list failed") {
-		t.Fatalf("SyncSkills() detail = %q, want both discovery failure reasons", result.Detail)
-	}
-}
-
-func TestSyncSkills_OfficialDiscoveryEmptyFallsBackToFullInstallWithReasons(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
-	runner := &fakeSkillsRunner{
-		officialIndexOut: `{"skills":[]}`,
-		installAllErr:    nil,
-	}
-
-	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
-	if result.Action != "fallback_synced" {
-		t.Fatalf("SyncSkills() action = %q, want fallback_synced", result.Action)
-	}
-	if runner.installedAll != 1 {
-		t.Fatalf("installedAll = %d, want 1", runner.installedAll)
-	}
-	if !strings.Contains(result.Detail, "official skills index contains no skills") || !strings.Contains(result.Detail, "official skills list returned no skills") {
-		t.Fatalf("SyncSkills() detail = %q, want both empty discovery reasons", result.Detail)
-	}
-}
-
 func TestSyncSkills_ListOfficialFailureFallsBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexErr: fmt.Errorf("index unavailable"),
-		officialErr:      fmt.Errorf("list failed"),
-		installAllErr:    nil,
+		officialErr:   fmt.Errorf("list failed"),
+		installAllErr: nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -506,9 +322,8 @@ func TestSyncSkills_ListOfficialFailureAndFullInstallFails(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexErr: fmt.Errorf("index unavailable"),
-		officialErr:      fmt.Errorf("list failed"),
-		installAllErr:    fmt.Errorf("full install failed"),
+		officialErr:   fmt.Errorf("list failed"),
+		installAllErr: fmt.Errorf("full install failed"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -527,10 +342,9 @@ func TestSyncSkills_GlobalJSONFailureFallsBackToTextList(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
-		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONErr:    fmt.Errorf("json list failed"),
-		globalOut:        globalSkillsOutput("lark-calendar"),
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONErr: fmt.Errorf("json list failed"),
+		globalOut:     globalSkillsOutput("lark-calendar"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -553,10 +367,9 @@ func TestSyncSkills_LocalListsFailureFallsBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
-		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONErr:    fmt.Errorf("json list failed with /Users/example/.agents/skills/lark-calendar agents Codex"),
-		globalErr:        fmt.Errorf("text list failed with /Users/example/.agents/skills/lark-mail agents Codex"),
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONErr: fmt.Errorf("json list failed with /Users/example/.agents/skills/lark-calendar agents Codex"),
+		globalErr:     fmt.Errorf("text list failed with /Users/example/.agents/skills/lark-mail agents Codex"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -578,10 +391,9 @@ func TestSyncSkills_ParseEmptyLocalListsFallBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
-		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONOut:    `[]`,
-		globalOut:        "Some unrecognized output format\n",
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut: `[]`,
+		globalOut:     "Some unrecognized output format\n",
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -608,10 +420,9 @@ func TestSyncSkills_EmptyToUpdateFallsBackToFullInstall(t *testing.T) {
 	}
 
 	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
-		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalOut:        globalSkillsOutput(),
-		installAllErr:    nil,
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalOut:     globalSkillsOutput(),
+		installAllErr: nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -634,12 +445,11 @@ func TestSyncSkills_InstallFailureFallsBackToFullInstall(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
-		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-mail"),
-		globalOut:        globalSkillsOutput("lark-calendar", "lark-mail"),
-		installErr:       fmt.Errorf("incremental boom"),
-		installAllErr:    nil,
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-mail"),
+		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
+		installErr:    fmt.Errorf("incremental boom"),
+		installAllErr: nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -667,12 +477,11 @@ func TestSyncSkills_InstallFailureAndFullInstallFails(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
-		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-mail"),
-		globalOut:        globalSkillsOutput("lark-calendar", "lark-mail"),
-		installErr:       fmt.Errorf("incremental boom"),
-		installAllErr:    fmt.Errorf("full install boom"),
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-mail"),
+		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
+		installErr:    fmt.Errorf("incremental boom"),
+		installAllErr: fmt.Errorf("full install boom"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -701,9 +510,8 @@ func TestSyncSkills_ParseEmptyWithNonEmptyStdoutFallsBack(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexErr: fmt.Errorf("index unavailable"),
-		officialOut:      "Some unrecognized output format\n",
-		installAllErr:    nil,
+		officialOut:   "Some unrecognized output format\n",
+		installAllErr: nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -719,9 +527,8 @@ func TestSyncSkills_ParseEmptyWithNonEmptyStdoutAndFullInstallFails(t *testing.T
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexErr: fmt.Errorf("index unavailable"),
-		officialOut:      "Some unrecognized output format\n",
-		installAllErr:    fmt.Errorf("full install failed"),
+		officialOut:   "Some unrecognized output format\n",
+		installAllErr: fmt.Errorf("full install failed"),
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -744,9 +551,8 @@ func TestSyncSkills_FallbackWithUnknownOfficialWritesMinimalState(t *testing.T)
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexErr: fmt.Errorf("index unavailable"),
-		officialOut:      "Some unrecognized output format\n",
-		installAllErr:    nil,
+		officialOut:   "Some unrecognized output format\n",
+		installAllErr: nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -770,12 +576,11 @@ func TestSyncSkills_FallbackWithKnownOfficialWritesFullState(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
-		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-mail"),
-		globalOut:        globalSkillsOutput("lark-calendar", "lark-mail"),
-		installErr:       fmt.Errorf("incremental boom"),
-		installAllErr:    nil,
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-mail"),
+		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
+		installErr:    fmt.Errorf("incremental boom"),
+		installAllErr: nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -796,12 +601,11 @@ func TestSyncSkills_FallbackResultContainsMetadata(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
-		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-mail"),
-		globalOut:        globalSkillsOutput("lark-calendar", "lark-mail"),
-		installErr:       fmt.Errorf("incremental boom"),
-		installAllErr:    nil,
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-mail"),
+		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
+		installErr:    fmt.Errorf("incremental boom"),
+		installAllErr: nil,
 	}
 
 	result := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -821,9 +625,8 @@ func TestSyncSkills_FallbackBreaksDegradationLoop(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", dir)
 	runner := &fakeSkillsRunner{
-		officialIndexErr: fmt.Errorf("index unavailable"),
-		officialErr:      fmt.Errorf("list failed"),
-		installAllErr:    nil,
+		officialErr:   fmt.Errorf("list failed"),
+		installAllErr: nil,
 	}
 
 	result1 := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner, Now: time.Now})
@@ -840,10 +643,9 @@ func TestSyncSkills_FallbackBreaksDegradationLoop(t *testing.T) {
 	}
 
 	runner2 := &fakeSkillsRunner{
-		officialIndexOut: officialSkillsIndexOutput("lark-calendar", "lark-mail"),
-		officialOut:      officialSkillsOutput("lark-calendar", "lark-mail"),
-		globalJSONOut:    globalSkillsJSONOutput("lark-calendar", "lark-mail"),
-		globalOut:        globalSkillsOutput("lark-calendar", "lark-mail"),
+		officialOut:   officialSkillsOutput("lark-calendar", "lark-mail"),
+		globalJSONOut: globalSkillsJSONOutput("lark-calendar", "lark-mail"),
+		globalOut:     globalSkillsOutput("lark-calendar", "lark-mail"),
 	}
 	result2 := SyncSkills(SyncOptions{Version: "1.0.33", Runner: runner2, Now: time.Now})
 	if result2.Action != "synced" {

lint/errscontract/rule_no_legacy_common_helper_call.go

@@ -19,10 +19,8 @@ var migratedCommonHelperPaths = []string{
 	"shortcuts/calendar/",
 	"shortcuts/drive/",
 	"shortcuts/mail/",
-	"shortcuts/minutes/",
 	"shortcuts/okr/",
 	"shortcuts/task/",
-	"shortcuts/vc/",
 	"shortcuts/whiteboard/",
 }
 

lint/errscontract/rule_no_legacy_envelope_literal.go

@@ -20,10 +20,8 @@ var migratedEnvelopePaths = []string{
 	"shortcuts/calendar/",
 	"shortcuts/drive/",
 	"shortcuts/mail/",
-	"shortcuts/minutes/",
 	"shortcuts/okr/",
 	"shortcuts/task/",
-	"shortcuts/vc/",
 	"shortcuts/whiteboard/",
 	"shortcuts/im/",
 }

shortcuts/common/drive_meta.go

@@ -23,7 +23,7 @@ func FetchDriveMeta(runtime *RuntimeContext, token, docType string, withURL bool
 		body["with_url"] = true
 	}
 
-	data, err := runtime.CallAPITyped(
+	data, err := runtime.CallAPI(
 		"POST",
 		"/open-apis/drive/v1/metas/batch_query",
 		nil,

shortcuts/common/drive_meta_test.go

@@ -10,7 +10,6 @@ import (
 	"sync/atomic"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -104,13 +103,6 @@ func TestFetchDriveMetaTitle(t *testing.T) {
 		if err == nil {
 			t.Fatal("FetchDriveMetaTitle() expected error, got nil")
 		}
-		p, ok := errs.ProblemOf(err)
-		if !ok {
-			t.Fatalf("expected typed error, got %T", err)
-		}
-		if p.Code != 99991668 {
-			t.Fatalf("code = %d, want 99991668", p.Code)
-		}
 	})
 }
 

shortcuts/common/validate.go

@@ -106,6 +106,25 @@ func ExactlyOneTyped(rt *RuntimeContext, flags ...string) error {
 	return MutuallyExclusiveTyped(rt, flags...)
 }
 
+// ValidatePageSize validates that the named flag (if set) is an integer within [minVal, maxVal].
+// It returns the parsed value (or defaultVal if the flag is empty) and any validation error.
+//
+// Deprecated: use ValidatePageSizeTyped for typed error envelopes.
+func ValidatePageSize(rt *RuntimeContext, flagName string, defaultVal, minVal, maxVal int) (int, error) {
+	s := rt.Str(flagName)
+	if s == "" {
+		return defaultVal, nil
+	}
+	n, err := strconv.Atoi(s)
+	if err != nil {
+		return 0, FlagErrorf("invalid --%s %q: must be an integer", flagName, s)
+	}
+	if n < minVal || n > maxVal {
+		return 0, FlagErrorf("invalid --%s %d: must be between %d and %d", flagName, n, minVal, maxVal)
+	}
+	return n, nil
+}
+
 // ValidatePageSizeTyped validates that the named flag (if set) is an integer within [minVal, maxVal].
 // It returns the parsed value (or defaultVal if the flag is empty) and any validation error.
 func ValidatePageSizeTyped(rt *RuntimeContext, flagName string, defaultVal, minVal, maxVal int) (int, error) {

shortcuts/doc/docs_create.go

@@ -5,13 +5,35 @@ package doc
 
 import (
 	"context"
+	"strings"
+
+	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// v1CreateFlags returns hidden parse-only compatibility flags for old v1 commands.
+// v1CreateFlags returns the flag definitions for the v1 (MCP) create path.
 func v1CreateFlags() []common.Flag {
-	return docsLegacyFlagDefinitions(docsCreateLegacyFlags())
+	return []common.Flag{
+		{Name: "title", Desc: "document title", Hidden: true},
+		{Name: "markdown", Desc: "Markdown content (Lark-flavored)", Hidden: true, Input: []string{common.File, common.Stdin}},
+		{Name: "folder-token", Desc: "parent folder token", Hidden: true},
+		{Name: "wiki-node", Desc: "wiki node token", Hidden: true},
+		{Name: "wiki-space", Desc: "wiki space ID (use my_library for personal library)", Hidden: true},
+	}
+}
+
+var docsCreateFlagVersions = buildFlagVersionMap(v1CreateFlags(), v2CreateFlags())
+
+// useV2Create returns true when the v2 (OpenAPI) create path should be used.
+// Explicit --api-version v2 takes priority; otherwise auto-detect by v2-only flags.
+func useV2Create(runtime *common.RuntimeContext) bool {
+	if runtime.Str("api-version") == "v2" {
+		return true
+	}
+	return runtime.Str("content") != "" ||
+		runtime.Str("parent-token") != "" ||
+		runtime.Str("parent-position") != ""
 }
 
 var DocsCreate = common.Shortcut{
@@ -21,25 +43,213 @@ var DocsCreate = common.Shortcut{
 	Risk:        "write",
 	AuthTypes:   []string{"user", "bot"},
 	Scopes:      []string{"docx:document:create"},
-	PostMount:   installDocsShortcutHelp("+create"),
+	Tips:        docsVersionSelectionTips,
 	Flags: concatFlags(
 		[]common.Flag{
-			docsAPIVersionCompatFlag(),
+			{Name: "api-version", Desc: "API version", Default: "v1", Enum: []string{"v1", "v2"}},
 		},
-		v2CreateFlags(),
 		v1CreateFlags(),
+		v2CreateFlags(),
 	),
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return validateCreateV2(ctx, runtime)
+		if useV2Create(runtime) {
+			return validateCreateV2(ctx, runtime)
+		}
+		return validateCreateV1(ctx, runtime)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		return dryRunCreateV2(ctx, runtime)
+		if useV2Create(runtime) {
+			return dryRunCreateV2(ctx, runtime)
+		}
+		return dryRunCreateV1(ctx, runtime)
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return executeCreateV2(ctx, runtime)
+		if useV2Create(runtime) {
+			return executeCreateV2(ctx, runtime)
+		}
+		return executeCreateV1(ctx, runtime)
+	},
+	PostMount: func(cmd *cobra.Command) {
+		installVersionedHelp(cmd, "v1", docsCreateFlagVersions)
 	},
 }
 
+// ── V1 (MCP) implementation ──
+
+func validateCreateV1(_ context.Context, runtime *common.RuntimeContext) error {
+	if runtime.Str("markdown") == "" {
+		return common.FlagErrorf("--markdown is required")
+	}
+	count := 0
+	if runtime.Str("folder-token") != "" {
+		count++
+	}
+	if runtime.Str("wiki-node") != "" {
+		count++
+	}
+	if runtime.Str("wiki-space") != "" {
+		count++
+	}
+	if count > 1 {
+		return common.FlagErrorf("--folder-token, --wiki-node, and --wiki-space are mutually exclusive")
+	}
+	return nil
+}
+
+func dryRunCreateV1(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	args := buildCreateArgsV1(runtime)
+	d := common.NewDryRunAPI().
+		POST(common.MCPEndpoint(runtime.Config.Brand)).
+		Desc("MCP tool: create-doc").
+		Body(map[string]interface{}{"method": "tools/call", "params": map[string]interface{}{"name": "create-doc", "arguments": args}}).
+		Set("mcp_tool", "create-doc").Set("args", args)
+	if runtime.IsBot() {
+		d.Desc("After create-doc succeeds in bot mode, the CLI will also try to grant the current CLI user full_access (可管理权限) on the new document.")
+	}
+	return d
+}
+
+func executeCreateV1(_ context.Context, runtime *common.RuntimeContext) error {
+	warnDeprecatedV1(runtime, "+create")
+	// Surface callout type= hint so users know to switch to background-color/
+	// border-color when they want a colored callout. Non-blocking, advisory.
+	if md := runtime.Str("markdown"); md != "" {
+		WarnCalloutType(md, runtime.IO().ErrOut)
+	}
+	args := buildCreateArgsV1(runtime)
+	result, err := common.CallMCPTool(runtime, "create-doc", args)
+	if err != nil {
+		return err
+	}
+	augmentCreateResultV1(runtime, result)
+	normalizeWhiteboardResult(result, runtime.Str("markdown"))
+	runtime.Out(result, nil)
+	return nil
+}
+
+func buildCreateArgsV1(runtime *common.RuntimeContext) map[string]interface{} {
+	md := runtime.Str("markdown")
+	args := map[string]interface{}{
+		"markdown": md,
+	}
+	if v := runtime.Str("title"); v != "" {
+		args["title"] = v
+	}
+	if v := runtime.Str("folder-token"); v != "" {
+		args["folder_token"] = v
+	}
+	if v := runtime.Str("wiki-node"); v != "" {
+		args["wiki_node"] = v
+	}
+	if v := runtime.Str("wiki-space"); v != "" {
+		args["wiki_space"] = v
+	}
+	return args
+}
+
+type docsPermissionTarget struct {
+	Token string
+	Type  string
+}
+
+func augmentCreateResultV1(runtime *common.RuntimeContext, result map[string]interface{}) {
+	target := selectPermissionTarget(result)
+	if grant := common.AutoGrantCurrentUserDrivePermission(runtime, target.Token, target.Type); grant != nil {
+		result["permission_grant"] = grant
+	}
+	fallbackDocURLV1(runtime, result)
+}
+
+// fallbackDocURLV1 fills result.doc_url with a brand-standard URL when the MCP
+// response did not include one but did include a doc_id. This protects against
+// degraded MCP responses (multi-content, non-JSON text) where ExtractMCPResult
+// drops structured fields.
+func fallbackDocURLV1(runtime *common.RuntimeContext, result map[string]interface{}) {
+	if strings.TrimSpace(common.GetString(result, "doc_url")) != "" {
+		return
+	}
+	docID := strings.TrimSpace(common.GetString(result, "doc_id"))
+	if docID == "" {
+		return
+	}
+	if u := common.BuildResourceURL(runtime.Config.Brand, "docx", docID); u != "" {
+		result["doc_url"] = u
+	}
+}
+
+func selectPermissionTarget(result map[string]interface{}) docsPermissionTarget {
+	if ref, ok := parsePermissionTargetFromURL(common.GetString(result, "doc_url")); ok {
+		return ref
+	}
+	docID := strings.TrimSpace(common.GetString(result, "doc_id"))
+	if docID != "" {
+		return docsPermissionTarget{Token: docID, Type: "docx"}
+	}
+	return docsPermissionTarget{}
+}
+
+func parsePermissionTargetFromURL(docURL string) (docsPermissionTarget, bool) {
+	if strings.TrimSpace(docURL) == "" {
+		return docsPermissionTarget{}, false
+	}
+	ref, err := parseDocumentRef(docURL)
+	if err != nil {
+		return docsPermissionTarget{}, false
+	}
+	switch ref.Kind {
+	case "wiki":
+		return docsPermissionTarget{Token: ref.Token, Type: "wiki"}, true
+	case "doc", "docx":
+		return docsPermissionTarget{Token: ref.Token, Type: ref.Kind}, true
+	default:
+		return docsPermissionTarget{}, false
+	}
+}
+
+// normalizeWhiteboardResult normalizes board_tokens in the MCP response when
+// whiteboard creation markdown is detected.
+func normalizeWhiteboardResult(result map[string]interface{}, markdown string) {
+	if !isWhiteboardCreateMarkdown(markdown) {
+		return
+	}
+	result["board_tokens"] = normalizeBoardTokens(result["board_tokens"])
+}
+
+func isWhiteboardCreateMarkdown(markdown string) bool {
+	lower := strings.ToLower(markdown)
+	if strings.Contains(lower, "```mermaid") || strings.Contains(lower, "```plantuml") {
+		return true
+	}
+	return strings.Contains(lower, "<whiteboard") &&
+		(strings.Contains(lower, `type="blank"`) || strings.Contains(lower, `type='blank'`))
+}
+
+func normalizeBoardTokens(raw interface{}) []string {
+	switch v := raw.(type) {
+	case nil:
+		return []string{}
+	case []string:
+		return v
+	case []interface{}:
+		tokens := make([]string, 0, len(v))
+		for _, item := range v {
+			if s, ok := item.(string); ok && s != "" {
+				tokens = append(tokens, s)
+			}
+		}
+		return tokens
+	case string:
+		if v == "" {
+			return []string{}
+		}
+		return []string{v}
+	default:
+		return []string{}
+	}
+}
+
+// ── Shared helpers ──
+
 // concatFlags combines multiple flag slices into one.
 func concatFlags(slices ...[]common.Flag) []common.Flag {
 	var out []common.Flag
@@ -48,3 +258,15 @@ func concatFlags(slices ...[]common.Flag) []common.Flag {
 	}
 	return out
 }
+
+// buildFlagVersionMap creates a flag name → version mapping from v1 and v2 flag lists.
+func buildFlagVersionMap(v1, v2 []common.Flag) map[string]string {
+	m := make(map[string]string, len(v1)+len(v2))
+	for _, f := range v1 {
+		m[f.Name] = "v1"
+	}
+	for _, f := range v2 {
+		m[f.Name] = "v2"
+	}
+	return m
+}

shortcuts/doc/docs_create_test.go

@@ -48,6 +48,7 @@ func TestDocsCreateV2BotAutoGrantSuccess(t *testing.T) {
 
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
+		"--api-version", "v2",
 		"--content", "<title>项目计划</title><h1>目标</h1>",
 		"--as", "bot",
 	})
@@ -248,63 +249,148 @@ func TestDocsCreateV2PreservesBackendURL(t *testing.T) {
 	}
 }
 
-func TestDocsCreateAPIVersionV1StillUsesV2Endpoint(t *testing.T) {
+// ── V1 (MCP) tests ──
+
+func TestDocsCreateV1BotAutoGrantSuccess(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, "ou_current_user"))
+	registerDocsCreateMCPStub(reg, map[string]interface{}{
+		"doc_id":  "doxcn_new_doc",
+		"doc_url": "https://example.feishu.cn/docx/doxcn_new_doc",
+		"message": "文档创建成功",
+	})
+
+	permStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/permissions/doxcn_new_doc/members",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"member": map[string]interface{}{
+					"member_id":   "ou_current_user",
+					"member_type": "openid",
+					"perm":        "full_access",
+				},
+			},
+		},
+	}
+	reg.Register(permStub)
+
+	err := runDocsCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--title", "项目计划",
+		"--markdown", "## 目标",
+		"--as", "bot",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDocsCreateEnvelope(t, stdout)
+	grant, _ := data["permission_grant"].(map[string]interface{})
+	if grant["status"] != common.PermissionGrantGranted {
+		t.Fatalf("permission_grant.status = %#v, want %q", grant["status"], common.PermissionGrantGranted)
+	}
+}
+
+func TestDocsCreateV1WikiSpaceAutoGrantFailure(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, "ou_current_user"))
+	registerDocsCreateMCPStub(reg, map[string]interface{}{
+		"doc_id":  "doxcn_new_doc",
+		"doc_url": "https://example.feishu.cn/wiki/wikcn_new_node",
+		"message": "文档创建成功",
+	})
+
+	permStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/permissions/wikcn_new_node/members",
+		Body: map[string]interface{}{
+			"code": 230001,
+			"msg":  "no permission",
+		},
+	}
+	reg.Register(permStub)
+
+	err := runDocsCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--markdown", "## 内容",
+		"--wiki-space", "my_library",
+		"--as", "bot",
+	})
+	if err != nil {
+		t.Fatalf("document creation should still succeed when auto-grant fails, got: %v", err)
+	}
+
+	data := decodeDocsCreateEnvelope(t, stdout)
+	grant, _ := data["permission_grant"].(map[string]interface{})
+	if grant["status"] != common.PermissionGrantFailed {
+		t.Fatalf("permission_grant.status = %#v, want %q", grant["status"], common.PermissionGrantFailed)
+	}
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(permStub.CapturedBody, &body); err != nil {
+		t.Fatalf("failed to parse permission request body: %v", err)
+	}
+	if body["perm_type"] != "container" {
+		t.Fatalf("permission request perm_type = %#v, want %q", body["perm_type"], "container")
+	}
+}
+
+func TestDocsCreateV1FallbackURLWhenBackendOmitsIt(t *testing.T) {
 	t.Parallel()
 
 	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
-	registerDocsCreateAPIStub(reg, map[string]interface{}{
-		"document": map[string]interface{}{
-			"document_id": "doxcn_new_doc",
-			"revision_id": float64(1),
-			"url":         "https://example.feishu.cn/docx/doxcn_new_doc",
-		},
+	registerDocsCreateMCPStub(reg, map[string]interface{}{
+		"doc_id":  "doxcn_new_doc",
+		"message": "文档创建成功",
+		// "doc_url" deliberately omitted to exercise the fallback.
 	})
 
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
 		"--api-version", "v1",
-		"--content", "<title>项目计划</title>",
+		"--title", "项目计划",
+		"--markdown", "## 目标",
 		"--as", "user",
 	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
+
 	data := decodeDocsCreateEnvelope(t, stdout)
-	doc, _ := data["document"].(map[string]interface{})
-	if got, want := doc["document_id"], "doxcn_new_doc"; got != want {
-		t.Fatalf("document.document_id = %#v, want %q", got, want)
+	if got, want := data["doc_url"], "https://www.feishu.cn/docx/doxcn_new_doc"; got != want {
+		t.Fatalf("doc_url = %#v, want %q (brand-standard fallback)", got, want)
 	}
 }
 
-func TestDocsCreateRejectsLegacyV1Flags(t *testing.T) {
+func TestDocsCreateV1PreservesBackendDocURL(t *testing.T) {
 	t.Parallel()
 
-	f, stdout, _, _ := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
+	registerDocsCreateMCPStub(reg, map[string]interface{}{
+		"doc_id":  "doxcn_new_doc",
+		"doc_url": "https://tenant.feishu.cn/docx/doxcn_new_doc",
+		"message": "文档创建成功",
+	})
+
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
+		"--api-version", "v1",
 		"--title", "项目计划",
 		"--markdown", "## 目标",
 		"--as", "user",
 	})
-	if err == nil {
-		t.Fatal("expected legacy v1 flags to be rejected")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
 	}
-	for _, want := range []string{
-		"docs +create is v2-only",
-		"the old v1 interface has been shut down",
-		"legacy v1 flag(s) --title, --markdown are no longer supported",
-		"--title -> put the title in --content",
-		"--markdown -> use --content with --doc-format markdown",
-		"lark-cli skills read lark-doc references/lark-doc-create.md",
-		"lark-cli skills read lark-doc references/lark-doc-xml.md",
-		"lark-cli skills read lark-doc references/lark-doc-md.md",
-		"follow the latest format rules",
-		"MUST NOT grep/open local SKILL.md files",
-		"lark-cli docs +create --help",
-	} {
-		if !strings.Contains(err.Error(), want) {
-			t.Fatalf("error missing %q: %v", want, err)
-		}
+
+	data := decodeDocsCreateEnvelope(t, stdout)
+	if got, want := data["doc_url"], "https://tenant.feishu.cn/docx/doxcn_new_doc"; got != want {
+		t.Fatalf("doc_url = %#v, want backend tenant URL %q (fallback must not overwrite)", got, want)
 	}
 }
 
@@ -335,6 +421,24 @@ func registerDocsCreateAPIStub(reg *httpmock.Registry, data map[string]interface
 	})
 }
 
+func registerDocsCreateMCPStub(reg *httpmock.Registry, result map[string]interface{}) {
+	payload, _ := json.Marshal(result)
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/mcp",
+		Body: map[string]interface{}{
+			"result": map[string]interface{}{
+				"content": []map[string]interface{}{
+					{
+						"type": "text",
+						"text": string(payload),
+					},
+				},
+			},
+		},
+	})
+}
+
 func runDocsCreateShortcut(t *testing.T, f *cmdutil.Factory, stdout *bytes.Buffer, args []string) error {
 	t.Helper()
 

shortcuts/doc/docs_create_v2.go

@@ -13,17 +13,14 @@ import (
 // v2CreateFlags returns the flag definitions for the v2 (OpenAPI) create path.
 func v2CreateFlags() []common.Flag {
 	return []common.Flag{
-		{Name: "content", Desc: "document body; XML by default or Markdown when --doc-format markdown. " + docsContentSkillHelp + "; use --help for the latest command flags", Input: []string{common.File, common.Stdin}},
-		{Name: "doc-format", Desc: "content format; xml is default and supports richer DocxXML blocks, markdown imports plain Markdown", Default: "xml", Enum: []string{"xml", "markdown"}},
-		{Name: "parent-token", Desc: "parent folder token or wiki node token; mutually exclusive with --parent-position"},
-		{Name: "parent-position", Desc: "parent position such as my_library; mutually exclusive with --parent-token"},
+		{Name: "content", Desc: "document content (XML or Markdown)", Hidden: true, Input: []string{common.File, common.Stdin}},
+		{Name: "doc-format", Desc: "content format (prefer XML)", Hidden: true, Default: "xml", Enum: []string{"xml", "markdown"}},
+		{Name: "parent-token", Desc: "parent folder or wiki-node token", Hidden: true},
+		{Name: "parent-position", Desc: "parent position (e.g. my_library)", Hidden: true},
 	}
 }
 
 func validateCreateV2(_ context.Context, runtime *common.RuntimeContext) error {
-	if err := validateDocsV2Only(runtime, "+create", docsCreateLegacyFlags()); err != nil {
-		return err
-	}
 	if runtime.Str("content") == "" {
 		return common.FlagErrorf("--content is required")
 	}

shortcuts/doc/docs_fetch.go

@@ -5,13 +5,40 @@ package doc
 
 import (
 	"context"
+	"fmt"
+	"io"
+	"strconv"
+
+	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// v1FetchFlags returns hidden parse-only compatibility flags for old v1 commands.
+// v1FetchFlags returns the flag definitions for the v1 (MCP) fetch path.
 func v1FetchFlags() []common.Flag {
-	return docsLegacyFlagDefinitions(docsFetchLegacyFlags())
+	return []common.Flag{
+		{Name: "offset", Desc: "pagination offset", Hidden: true},
+		{Name: "limit", Desc: "pagination limit", Hidden: true},
+	}
+}
+
+var docsFetchFlagVersions = buildFlagVersionMap(v1FetchFlags(), v2FetchFlags())
+
+// useV2Fetch returns true when the v2 (OpenAPI) fetch path should be used.
+// Explicit --api-version v2 takes priority; otherwise auto-detect by the
+// presence of any v2-only flag on the command line — we check pflag.Changed
+// rather than the value so that explicitly typing `--detail simple` (equal
+// to the default) still routes to v2.
+func useV2Fetch(runtime *common.RuntimeContext) bool {
+	if runtime.Str("api-version") == "v2" {
+		return true
+	}
+	for _, name := range []string{"detail", "doc-format", "scope", "revision-id", "start-block-id", "end-block-id", "keyword", "context-before", "context-after", "max-depth"} {
+		if runtime.Changed(name) {
+			return true
+		}
+	}
+	return false
 }
 
 var DocsFetch = common.Shortcut{
@@ -22,22 +49,88 @@ var DocsFetch = common.Shortcut{
 	Scopes:      []string{"docx:document:readonly"},
 	AuthTypes:   []string{"user", "bot"},
 	HasFormat:   true,
-	PostMount:   installDocsShortcutHelp("+fetch"),
+	Tips:        docsVersionSelectionTips,
 	Flags: concatFlags(
 		[]common.Flag{
-			docsAPIVersionCompatFlag(),
+			{Name: "api-version", Desc: "API version", Default: "v1", Enum: []string{"v1", "v2"}},
 			{Name: "doc", Desc: "document URL or token", Required: true},
 		},
-		v2FetchFlags(),
 		v1FetchFlags(),
+		v2FetchFlags(),
 	),
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return validateFetchV2(ctx, runtime)
+		if useV2Fetch(runtime) {
+			return validateFetchV2(ctx, runtime)
+		}
+		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		return dryRunFetchV2(ctx, runtime)
+		if useV2Fetch(runtime) {
+			return dryRunFetchV2(ctx, runtime)
+		}
+		return dryRunFetchV1(ctx, runtime)
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return executeFetchV2(ctx, runtime)
+		if useV2Fetch(runtime) {
+			return executeFetchV2(ctx, runtime)
+		}
+		return executeFetchV1(ctx, runtime)
+	},
+	PostMount: func(cmd *cobra.Command) {
+		installVersionedHelp(cmd, "v1", docsFetchFlagVersions)
 	},
 }
+
+// ── V1 (MCP) implementation ──
+
+func dryRunFetchV1(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	args := buildFetchArgsV1(runtime)
+	return common.NewDryRunAPI().
+		POST(common.MCPEndpoint(runtime.Config.Brand)).
+		Desc("MCP tool: fetch-doc").
+		Body(map[string]interface{}{"method": "tools/call", "params": map[string]interface{}{"name": "fetch-doc", "arguments": args}}).
+		Set("mcp_tool", "fetch-doc").Set("args", args)
+}
+
+func executeFetchV1(_ context.Context, runtime *common.RuntimeContext) error {
+	warnDeprecatedV1(runtime, "+fetch")
+	args := buildFetchArgsV1(runtime)
+
+	result, err := common.CallMCPTool(runtime, "fetch-doc", args)
+	if err != nil {
+		return err
+	}
+
+	if md, ok := result["markdown"].(string); ok {
+		result["markdown"] = fixExportedMarkdown(md)
+	}
+
+	runtime.OutFormat(result, nil, func(w io.Writer) {
+		if title, ok := result["title"].(string); ok && title != "" {
+			fmt.Fprintf(w, "# %s\n\n", title)
+		}
+		if md, ok := result["markdown"].(string); ok {
+			fmt.Fprintln(w, md)
+		}
+		if hasMore, ok := result["has_more"].(bool); ok && hasMore {
+			fmt.Fprintln(w, "\n--- more content available, use --offset and --limit to paginate ---")
+		}
+	})
+	return nil
+}
+
+func buildFetchArgsV1(runtime *common.RuntimeContext) map[string]interface{} {
+	args := map[string]interface{}{
+		"doc_id":           runtime.Str("doc"),
+		"skip_task_detail": true,
+	}
+	if v := runtime.Str("offset"); v != "" {
+		n, _ := strconv.Atoi(v)
+		args["offset"] = n
+	}
+	if v := runtime.Str("limit"); v != "" {
+		n, _ := strconv.Atoi(v)
+		args["limit"] = n
+	}
+	return args
+}

shortcuts/doc/docs_fetch_v2.go

@@ -16,16 +16,16 @@ import (
 // v2FetchFlags returns the flag definitions for the v2 (OpenAPI) fetch path.
 func v2FetchFlags() []common.Flag {
 	return []common.Flag{
-		{Name: "doc-format", Desc: "output content format; xml keeps DocxXML structure and optional block ids, markdown is plain export", Default: "xml", Enum: []string{"xml", "markdown"}},
-		{Name: "detail", Desc: "detail level; simple for reading, with-ids for block references, full for styles and edit metadata", Default: "simple", Enum: []string{"simple", "with-ids", "full"}},
-		{Name: "revision-id", Desc: "document revision id; -1 means latest", Type: "int", Default: "-1"},
-		{Name: "scope", Desc: "read scope; full reads whole doc, outline lists headings, section expands from heading anchor, range uses block ids, keyword searches text", Default: "full", Enum: []string{"full", "outline", "range", "keyword", "section"}},
-		{Name: "start-block-id", Desc: "range/section anchor block id; required for section and optional start for range"},
-		{Name: "end-block-id", Desc: "range end block id; -1 means through document end"},
-		{Name: "keyword", Desc: "keyword scope query; supports case-insensitive substring/regex fallback and '|' OR branches, e.g. foo|bar or bug|缺陷"},
-		{Name: "context-before", Desc: "range/keyword/section context: sibling blocks before selected top-level blocks", Type: "int", Default: "0"},
-		{Name: "context-after", Desc: "range/keyword/section context: sibling blocks after selected top-level blocks", Type: "int", Default: "0"},
-		{Name: "max-depth", Desc: "outline heading level cap; other scopes subtree depth where -1 is unlimited and 0 is block only", Type: "int", Default: "-1"},
+		{Name: "doc-format", Desc: "content format", Hidden: true, Default: "xml", Enum: []string{"xml", "markdown"}},
+		{Name: "detail", Desc: "export detail level: simple (read-only) | with-ids (block IDs for cross-referencing) | full (all attrs for editing)", Hidden: true, Default: "simple", Enum: []string{"simple", "with-ids", "full"}},
+		{Name: "revision-id", Desc: "document revision (-1 = latest)", Hidden: true, Type: "int", Default: "-1"},
+		{Name: "scope", Desc: "partial read scope: outline | range | keyword | section (omit to read whole doc)", Default: "full", Enum: []string{"full", "outline", "range", "keyword", "section"}},
+		{Name: "start-block-id", Desc: "range/section mode: start (anchor) block id"},
+		{Name: "end-block-id", Desc: "range mode: end block id; \"-1\" = to end of document"},
+		{Name: "keyword", Desc: "keyword mode: substring + regex match (case-insensitive); use '|' for OR branches, e.g. 'foo|bar' or 'bug|缺陷'"},
+		{Name: "context-before", Desc: "range/keyword/section mode: sibling blocks before match", Type: "int", Default: "0"},
+		{Name: "context-after", Desc: "range/keyword/section mode: sibling blocks after match", Type: "int", Default: "0"},
+		{Name: "max-depth", Desc: "outline: heading level cap; range/keyword/section: block subtree depth (-1 = unlimited)", Type: "int", Default: "-1"},
 	}
 }
 
@@ -33,9 +33,6 @@ func v2FetchFlags() []common.Flag {
 // --dry-run so that invalid input fails with a structured exit code (2) and
 // JSON envelope instead of slipping through dry-run as a "success".
 func validateFetchV2(_ context.Context, runtime *common.RuntimeContext) error {
-	if err := validateDocsV2Only(runtime, "+fetch", docsFetchLegacyFlags()); err != nil {
-		return err
-	}
 	if _, err := parseDocumentRef(runtime.Str("doc")); err != nil {
 		return common.FlagErrorf("invalid --doc: %v", err)
 	}

shortcuts/doc/docs_fetch_v2_test.go

@@ -5,7 +5,6 @@ package doc
 
 import (
 	"context"
-	"strings"
 	"testing"
 
 	"github.com/larksuite/cli/shortcuts/common"
@@ -59,82 +58,6 @@ func TestBuildFetchBodyOmitsEmptyScene(t *testing.T) {
 	}
 }
 
-func TestDocsFetchDryRunDefaultsToV2Endpoint(t *testing.T) {
-	t.Parallel()
-
-	runtime := newFetchShortcutTestRuntime(t, "", nil)
-	if err := validateFetchV2(context.Background(), runtime); err != nil {
-		t.Fatalf("validateFetchV2() error = %v", err)
-	}
-
-	dry := decodeDocDryRun(t, DocsFetch.DryRun(context.Background(), runtime))
-	if len(dry.API) != 1 {
-		t.Fatalf("expected 1 dry-run API call, got %d", len(dry.API))
-	}
-	if got, want := dry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnFetchDryRun/fetch"; got != want {
-		t.Fatalf("dry-run URL = %q, want %q", got, want)
-	}
-	if got, want := dry.API[0].Body["format"], "xml"; got != want {
-		t.Fatalf("dry-run format = %#v, want %q", got, want)
-	}
-}
-
-func TestDocsFetchAPIVersionV1StillUsesV2Endpoint(t *testing.T) {
-	t.Parallel()
-
-	runtime := newFetchShortcutTestRuntime(t, "v1", nil)
-	if err := validateFetchV2(context.Background(), runtime); err != nil {
-		t.Fatalf("validateFetchV2() error = %v", err)
-	}
-
-	dry := decodeDocDryRun(t, DocsFetch.DryRun(context.Background(), runtime))
-	if len(dry.API) != 1 {
-		t.Fatalf("expected 1 dry-run API call, got %d", len(dry.API))
-	}
-	if got, want := dry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnFetchDryRun/fetch"; got != want {
-		t.Fatalf("dry-run URL = %q, want %q", got, want)
-	}
-}
-
-func TestDocsFetchRejectsLegacyFlags(t *testing.T) {
-	tests := []struct {
-		name     string
-		setFlags map[string]string
-		want     []string
-	}{
-		{
-			name:     "legacy offset",
-			setFlags: map[string]string{"offset": "10"},
-			want: []string{
-				"docs +fetch is v2-only",
-				"the old v1 interface has been shut down",
-				"legacy v1 flag(s) --offset are no longer supported",
-				"--offset -> use --scope outline/range/keyword/section",
-				"lark-cli skills read lark-doc references/lark-doc-fetch.md",
-				"MUST NOT grep/open local SKILL.md files",
-				"lark-cli docs +fetch --help",
-			},
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
-			runtime := newFetchShortcutTestRuntime(t, "", tt.setFlags)
-			err := validateFetchV2(context.Background(), runtime)
-			if err == nil {
-				t.Fatal("expected v2-only validation error")
-			}
-			for _, want := range tt.want {
-				if !strings.Contains(err.Error(), want) {
-					t.Fatalf("error missing %q: %v", want, err)
-				}
-			}
-		})
-	}
-}
-
 func newFetchBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
 	cmd := &cobra.Command{Use: "+fetch"}
 	cmd.Flags().String("doc-format", "xml", "")
@@ -150,37 +73,6 @@ func newFetchBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
 	return common.TestNewRuntimeContextWithCtx(ctx, cmd, nil)
 }
 
-func newFetchShortcutTestRuntime(t *testing.T, apiVersion string, setFlags map[string]string) *common.RuntimeContext {
-	t.Helper()
-
-	cmd := &cobra.Command{Use: "+fetch"}
-	cmd.Flags().String("api-version", "", "")
-	cmd.Flags().String("doc", "doxcnFetchDryRun", "")
-	cmd.Flags().String("doc-format", "xml", "")
-	cmd.Flags().String("detail", "simple", "")
-	cmd.Flags().Int("revision-id", -1, "")
-	cmd.Flags().String("scope", "full", "")
-	cmd.Flags().String("start-block-id", "", "")
-	cmd.Flags().String("end-block-id", "", "")
-	cmd.Flags().String("keyword", "", "")
-	cmd.Flags().Int("context-before", 0, "")
-	cmd.Flags().Int("context-after", 0, "")
-	cmd.Flags().Int("max-depth", -1, "")
-	cmd.Flags().String("offset", "", "")
-	cmd.Flags().String("limit", "", "")
-	if apiVersion != "" {
-		if err := cmd.Flags().Set("api-version", apiVersion); err != nil {
-			t.Fatalf("set api-version: %v", err)
-		}
-	}
-	for name, value := range setFlags {
-		if err := cmd.Flags().Set(name, value); err != nil {
-			t.Fatalf("set %s: %v", name, err)
-		}
-	}
-	return common.TestNewRuntimeContext(cmd, nil)
-}
-
 func newCreateBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
 	cmd := &cobra.Command{Use: "+create"}
 	cmd.Flags().String("doc-format", "xml", "")

shortcuts/doc/docs_update.go

@@ -5,13 +5,57 @@ package doc
 
 import (
 	"context"
+	"fmt"
+	"regexp"
+	"strings"
+
+	"github.com/spf13/cobra"
 
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-// v1UpdateFlags returns hidden parse-only compatibility flags for old v1 commands.
+var validModesV1 = map[string]bool{
+	"append":        true,
+	"overwrite":     true,
+	"replace_range": true,
+	"replace_all":   true,
+	"insert_before": true,
+	"insert_after":  true,
+	"delete_range":  true,
+}
+
+var needsSelectionV1 = map[string]bool{
+	"replace_range": true,
+	"replace_all":   true,
+	"insert_before": true,
+	"insert_after":  true,
+	"delete_range":  true,
+}
+
+// v1UpdateFlags returns the flag definitions for the v1 (MCP) update path.
 func v1UpdateFlags() []common.Flag {
-	return docsLegacyFlagDefinitions(docsUpdateLegacyFlags())
+	return []common.Flag{
+		{Name: "mode", Desc: "update mode: append | overwrite | replace_range | replace_all | insert_before | insert_after | delete_range", Hidden: true},
+		{Name: "markdown", Desc: "new content (Lark-flavored Markdown; create blank whiteboards with <whiteboard type=\"blank\"></whiteboard>, repeat to create multiple boards)", Hidden: true, Input: []string{common.File, common.Stdin}},
+		{Name: "selection-with-ellipsis", Desc: "content locator (e.g. 'start...end')", Hidden: true},
+		{Name: "selection-by-title", Desc: "title locator (e.g. '## Section')", Hidden: true},
+		{Name: "new-title", Desc: "also update document title", Hidden: true},
+	}
+}
+
+var docsUpdateFlagVersions = buildFlagVersionMap(v1UpdateFlags(), v2UpdateFlags())
+
+// useV2Update returns true when the v2 (OpenAPI) update path should be used.
+// Explicit --api-version v2 takes priority; otherwise auto-detect by v2-only flags.
+func useV2Update(runtime *common.RuntimeContext) bool {
+	if runtime.Str("api-version") == "v2" {
+		return true
+	}
+	return runtime.Str("command") != "" ||
+		runtime.Str("content") != "" ||
+		runtime.Str("pattern") != "" ||
+		runtime.Str("block-id") != "" ||
+		runtime.Str("src-block-ids") != ""
 }
 
 var DocsUpdate = common.Shortcut{
@@ -21,22 +65,225 @@ var DocsUpdate = common.Shortcut{
 	Risk:        "write",
 	Scopes:      []string{"docx:document:write_only", "docx:document:readonly"},
 	AuthTypes:   []string{"user", "bot"},
-	PostMount:   installDocsShortcutHelp("+update"),
+	Tips:        docsVersionSelectionTips,
 	Flags: concatFlags(
 		[]common.Flag{
-			docsAPIVersionCompatFlag(),
+			{Name: "api-version", Desc: "API version", Default: "v1", Enum: []string{"v1", "v2"}},
 			{Name: "doc", Desc: "document URL or token", Required: true},
 		},
-		v2UpdateFlags(),
 		v1UpdateFlags(),
+		v2UpdateFlags(),
 	),
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return validateUpdateV2(ctx, runtime)
+		if useV2Update(runtime) {
+			return validateUpdateV2(ctx, runtime)
+		}
+		return validateUpdateV1(ctx, runtime)
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		return dryRunUpdateV2(ctx, runtime)
+		if useV2Update(runtime) {
+			return dryRunUpdateV2(ctx, runtime)
+		}
+		return dryRunUpdateV1(ctx, runtime)
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return executeUpdateV2(ctx, runtime)
+		if useV2Update(runtime) {
+			return executeUpdateV2(ctx, runtime)
+		}
+		return executeUpdateV1(ctx, runtime)
+	},
+	PostMount: func(cmd *cobra.Command) {
+		installVersionedHelp(cmd, "v1", docsUpdateFlagVersions)
 	},
 }
+
+// ── V1 (MCP) implementation ──
+
+func validateUpdateV1(_ context.Context, runtime *common.RuntimeContext) error {
+	mode := runtime.Str("mode")
+	if mode == "" {
+		return common.FlagErrorf("--mode is required")
+	}
+	if !validModesV1[mode] {
+		return common.FlagErrorf("invalid --mode %q, valid: append | overwrite | replace_range | replace_all | insert_before | insert_after | delete_range", mode)
+	}
+
+	if mode != "delete_range" && runtime.Str("markdown") == "" {
+		return common.FlagErrorf("--%s mode requires --markdown", mode)
+	}
+
+	selEllipsis := runtime.Str("selection-with-ellipsis")
+	selTitle := runtime.Str("selection-by-title")
+	if selEllipsis != "" && selTitle != "" {
+		return common.FlagErrorf("--selection-with-ellipsis and --selection-by-title are mutually exclusive")
+	}
+
+	if needsSelectionV1[mode] && selEllipsis == "" && selTitle == "" {
+		return common.FlagErrorf(selectionRequiredMessageV1(mode))
+	}
+	if err := validateSelectionByTitleV1(selTitle); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+func selectionRequiredMessageV1(mode string) string {
+	msg := fmt.Sprintf("--%s mode requires --selection-with-ellipsis or --selection-by-title", mode)
+	if mode == "replace_all" {
+		msg += ". If you intended to replace the entire document body, use --mode overwrite instead."
+	}
+	return msg
+}
+
+func validateSelectionByTitleV1(title string) error {
+	if title == "" {
+		return nil
+	}
+	trimmed := strings.TrimSpace(title)
+	if strings.Contains(trimmed, "\n") || strings.Contains(trimmed, "\r") {
+		return common.FlagErrorf("--selection-by-title must be a single heading line (for example: '## Section')")
+	}
+	if strings.HasPrefix(trimmed, "#") {
+		return nil
+	}
+	return common.FlagErrorf("--selection-by-title must include markdown heading prefix '#'. Example: --selection-by-title '## Section'")
+}
+
+func dryRunUpdateV1(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	args := buildUpdateArgsV1(runtime)
+	return common.NewDryRunAPI().
+		POST(common.MCPEndpoint(runtime.Config.Brand)).
+		Desc("MCP tool: update-doc").
+		Body(map[string]interface{}{"method": "tools/call", "params": map[string]interface{}{"name": "update-doc", "arguments": args}}).
+		Set("mcp_tool", "update-doc").Set("args", args)
+}
+
+func executeUpdateV1(_ context.Context, runtime *common.RuntimeContext) error {
+	warnDeprecatedV1(runtime, "+update")
+
+	// Static semantic checks run before the MCP call so users see
+	// warnings even if the subsequent request fails. They never block
+	// execution — the update still proceeds.
+	for _, w := range docsUpdateWarnings(runtime.Str("mode"), runtime.Str("markdown")) {
+		fmt.Fprintf(runtime.IO().ErrOut, "warning: %s\n", w)
+	}
+
+	// Overwrite replaces the entire document, silently discarding any
+	// whiteboard or file-attachment blocks that cannot be re-created from
+	// Markdown. Pre-fetch the current content and warn when such blocks
+	// are present so the caller can take a backup before proceeding.
+	if runtime.Str("mode") == "overwrite" {
+		if w := warnOverwriteResourceBlocks(runtime); w != "" {
+			fmt.Fprintf(runtime.IO().ErrOut, "warning: %s\n", w)
+		}
+	}
+
+	// Surface callout type= hint so users know to switch to background-color/
+	// border-color when they want a colored callout. Non-blocking, advisory.
+	if md := runtime.Str("markdown"); md != "" {
+		WarnCalloutType(md, runtime.IO().ErrOut)
+	}
+
+	args := buildUpdateArgsV1(runtime)
+
+	result, err := common.CallMCPTool(runtime, "update-doc", args)
+	if err != nil {
+		return err
+	}
+
+	normalizeWhiteboardResult(result, runtime.Str("markdown"))
+	runtime.Out(result, nil)
+	return nil
+}
+
+func buildUpdateArgsV1(runtime *common.RuntimeContext) map[string]interface{} {
+	args := map[string]interface{}{
+		"doc_id": runtime.Str("doc"),
+		"mode":   runtime.Str("mode"),
+	}
+	if v := runtime.Str("markdown"); v != "" {
+		args["markdown"] = v
+	}
+	if v := runtime.Str("selection-with-ellipsis"); v != "" {
+		args["selection_with_ellipsis"] = v
+	}
+	if v := runtime.Str("selection-by-title"); v != "" {
+		args["selection_by_title"] = v
+	}
+	if v := runtime.Str("new-title"); v != "" {
+		args["new_title"] = v
+	}
+	return args
+}
+
+// resourceBlockRe matches the opening of a <whiteboard …> or <file …> tag
+// (followed by whitespace, > or /) to avoid false positives on tag names like
+// <file-view> or prose that merely mentions the word "whiteboard".
+var resourceBlockRe = regexp.MustCompile(`<(whiteboard|file)[\s/>]`)
+
+// warnOverwriteResourceBlocks pre-fetches the current document and returns a
+// non-empty warning string when the document contains whiteboard or file
+// attachment blocks that would be permanently deleted by an overwrite. Returns
+// an empty string (no warning) when the document is clean or the fetch fails
+// (we never block the overwrite on a best-effort check).
+//
+// This function is not unit-tested because it depends on an external MCP call
+// (fetch-doc). The pure detection logic lives in checkOverwriteResourceBlocks,
+// which has full table-driven coverage.
+//
+// Performance: this adds one extra fetch-doc round-trip to every --mode overwrite
+// call, even when the document has no resource blocks. The cost is intentional:
+// the guard is best-effort and silent on failure, so the latency is bounded and
+// the trade-off is acceptable to avoid silent data loss.
+func warnOverwriteResourceBlocks(runtime *common.RuntimeContext) string {
+	args := map[string]interface{}{
+		"doc_id": runtime.Str("doc"),
+		// skip_task_detail reduces response payload by omitting per-block task
+		// metadata, making the pre-fetch faster and cheaper.
+		"skip_task_detail": true,
+	}
+	result, err := common.CallMCPTool(runtime, "fetch-doc", args)
+	if err != nil {
+		// Fetch failed — silently skip the guard rather than blocking overwrite.
+		return ""
+	}
+	md, _ := result["markdown"].(string)
+	return checkOverwriteResourceBlocks(md)
+}
+
+// checkOverwriteResourceBlocks scans Markdown for resource block tags that
+// cannot survive an overwrite: <whiteboard …> and <file …>. Returns a
+// warning string listing the counts if any are found, empty string otherwise.
+func checkOverwriteResourceBlocks(markdown string) string {
+	matches := resourceBlockRe.FindAllStringSubmatch(markdown, -1)
+	whiteboards, files := 0, 0
+	for _, m := range matches {
+		switch m[1] {
+		case "whiteboard":
+			whiteboards++
+		case "file":
+			files++
+		}
+	}
+	var found []string
+	if whiteboards == 1 {
+		found = append(found, "1 whiteboard block")
+	} else if whiteboards > 1 {
+		found = append(found, fmt.Sprintf("%d whiteboard blocks", whiteboards))
+	}
+	if files == 1 {
+		found = append(found, "1 file attachment block")
+	} else if files > 1 {
+		found = append(found, fmt.Sprintf("%d file attachment blocks", files))
+	}
+	if len(found) == 0 {
+		return ""
+	}
+	return fmt.Sprintf(
+		"the document contains %s that cannot be reconstructed from Markdown; "+
+			"overwrite will permanently delete them. "+
+			"Consider fetching a backup with `docs +fetch` before overwriting.",
+		strings.Join(found, " and "),
+	)
+}

shortcuts/doc/docs_update_check.go

@@ -0,0 +1,281 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"regexp"
+	"strings"
+)
+
+// docsUpdateWarnings returns a list of human-readable warnings for a
+// `docs +update` invocation based on static analysis of the mode and
+// Markdown payload. The warnings describe CLI/MCP contract edges that
+// commonly surprise users; the update is still executed — callers
+// decide whether to stop at a warning.
+//
+// Both checks ignore fenced code blocks (```…``` and ~~~…~~~, with up
+// to 3 leading spaces per CommonMark §4.5), inline code spans, and
+// backslash-escaped emphasis markers so that literal Markdown content
+// embedded in code samples or escaped prose does not produce false
+// positives.
+//
+// Warnings emitted (current):
+//
+//  1. replace_* modes do not split blocks. A Markdown payload containing
+//     a blank line (\n\n) in prose implies the caller expects multiple
+//     paragraphs, but replace_range / replace_all only swap in-block
+//     text. The resulting block will contain the blank line as literal
+//     text and appear as a single paragraph in the UI.
+//
+//  2. Lark does not round-trip bold+italic. Six shapes are detected:
+//     ***text***   ___text___
+//     **_text_**   __*text*__
+//     _**text**_   *__text__*
+//     Lark stores only one of the two emphases (usually italic), silently
+//     dropping the other. The user wanted both; they will get one.
+func docsUpdateWarnings(mode, markdown string) []string {
+	var warnings []string
+	if w := checkDocsUpdateReplaceMultilineMarkdown(mode, markdown); w != "" {
+		warnings = append(warnings, w)
+	}
+	if w := checkDocsUpdateBoldItalic(markdown); w != "" {
+		warnings = append(warnings, w)
+	}
+	return warnings
+}
+
+// checkDocsUpdateReplaceMultilineMarkdown flags markdown that contains a
+// blank-line paragraph break outside fenced code blocks under a replace_*
+// mode. Blank lines inside code fences are literal content and don't
+// imply paragraph semantics, so they are deliberately ignored.
+func checkDocsUpdateReplaceMultilineMarkdown(mode, markdown string) string {
+	if mode != "replace_range" && mode != "replace_all" {
+		return ""
+	}
+	// A CR/LF-robust check: both "\n\n" and "\r\n\r\n" count as paragraph
+	// separators. We normalize line endings once before detection.
+	normalized := strings.ReplaceAll(markdown, "\r\n", "\n")
+	if !proseHasBlankLine(normalized) {
+		return ""
+	}
+	return "--mode=" + mode + " does not split a block into multiple paragraphs; " +
+		"the blank line in --markdown will render as literal text. " +
+		"For multiple paragraphs, use --mode=delete_range followed by --mode=insert_before."
+}
+
+// combinedEmphasisPatterns holds the six documented combined-emphasis shapes
+// that Lark downgrades to a single emphasis. Each entry pairs a regex with a
+// short shape label for the warning message. The two forms per shape (with
+// and without `[^…]*?`) are there because the lazy quantifier needs at least
+// one non-delimiter character to match; single-rune payloads (e.g. `***X***`)
+// take the second alternation.
+var combinedEmphasisPatterns = []struct {
+	shape string
+	re    *regexp.Regexp
+}{
+	// Bold+italic with a single delimiter char.
+	{"***text***", regexp.MustCompile(`\*\*\*\S[^*]*?\S\*\*\*|\*\*\*\S\*\*\*`)},
+	{"___text___", regexp.MustCompile(`___\S[^_]*?\S___|___\S___`)},
+
+	// Bold wrapping italic (asterisk outside).
+	{"**_text_**", regexp.MustCompile(`\*\*_\S[^_*]*?\S_\*\*|\*\*_\S_\*\*`)},
+	{"__*text*__", regexp.MustCompile(`__\*\S[^_*]*?\S\*__|__\*\S\*__`)},
+
+	// Italic wrapping bold (asterisk inside).
+	{"_**text**_", regexp.MustCompile(`_\*\*\S[^_*]*?\S\*\*_|_\*\*\S\*\*_`)},
+	{"*__text__*", regexp.MustCompile(`\*__\S[^_*]*?\S__\*|\*__\S__\*`)},
+}
+
+// checkDocsUpdateBoldItalic flags Markdown emphases that attempt to
+// combine bold and italic in a way Lark cannot represent. Fenced code
+// blocks, inline code spans, and backslash-escaped emphasis markers are
+// stripped first so that literal markdown examples ("here is a
+// `***keyword***` to flag") do not trigger the warning.
+func checkDocsUpdateBoldItalic(markdown string) string {
+	if markdown == "" {
+		return ""
+	}
+	sanitized := stripEscapedEmphasisMarkers(stripMarkdownCodeRegions(markdown))
+	for _, p := range combinedEmphasisPatterns {
+		if p.re.MatchString(sanitized) {
+			return "Lark does not support combined bold+italic markers " +
+				"(e.g. ***text***, ___text___, **_text_**, _**text**_, __*text*__, *__text__*); " +
+				"the emphasis will be downgraded to either bold or italic. " +
+				"Split into two separate emphases or drop one of them."
+		}
+	}
+	return ""
+}
+
+// proseHasBlankLine reports whether markdown contains a blank line outside
+// of fenced code blocks. Blank lines inside ```...``` or ~~~...~~~ fences
+// are code content, not paragraph separators, and must not trip the
+// "replace_* cannot split paragraphs" warning.
+//
+// A blank line counts only when it sits between two non-blank boundaries
+// (other prose, or a fence open/close). A trailing empty line at EOF is
+// not treated as "\n\n".
+func proseHasBlankLine(markdown string) bool {
+	lines := strings.Split(markdown, "\n")
+	inFence := false
+	var fenceMarker string
+	for i, line := range lines {
+		if inFence {
+			if isCodeFenceClose(line, fenceMarker) {
+				inFence = false
+				fenceMarker = ""
+			}
+			continue
+		}
+		if marker := codeFenceOpenMarker(line); marker != "" {
+			inFence = true
+			fenceMarker = marker
+			continue
+		}
+		if strings.TrimSpace(line) == "" && i > 0 && i+1 < len(lines) {
+			return true
+		}
+	}
+	return false
+}
+
+// stripMarkdownCodeRegions returns markdown with fenced code blocks blanked
+// out and inline code spans replaced by whitespace of equivalent length.
+// Byte offsets outside the masked regions are preserved, so follow-on
+// regex matches still point at real prose positions.
+func stripMarkdownCodeRegions(markdown string) string {
+	lines := strings.Split(markdown, "\n")
+	inFence := false
+	var fenceMarker string
+	for i, line := range lines {
+		if inFence {
+			if isCodeFenceClose(line, fenceMarker) {
+				inFence = false
+				fenceMarker = ""
+			}
+			lines[i] = ""
+			continue
+		}
+		if marker := codeFenceOpenMarker(line); marker != "" {
+			inFence = true
+			fenceMarker = marker
+			lines[i] = ""
+			continue
+		}
+		lines[i] = maskInlineCodeSpans(line)
+	}
+	return strings.Join(lines, "\n")
+}
+
+// maskInlineCodeSpans replaces the byte ranges of any inline code spans in
+// line with space characters of equal length. Uses scanInlineCodeSpans from
+// markdown_fix.go, which implements the CommonMark §6.1 matching-backtick-run
+// rule (so “ `a`b` “ is a single span).
+func maskInlineCodeSpans(line string) string {
+	spans := scanInlineCodeSpans(line)
+	if len(spans) == 0 {
+		return line
+	}
+	var sb strings.Builder
+	pos := 0
+	for _, loc := range spans {
+		sb.WriteString(line[pos:loc[0]])
+		sb.WriteString(strings.Repeat(" ", loc[1]-loc[0]))
+		pos = loc[1]
+	}
+	sb.WriteString(line[pos:])
+	return sb.String()
+}
+
+// stripEscapedEmphasisMarkers removes backslash-escaped '*' and '_' so the
+// bold/italic regexes don't treat literal sequences like `\***text***` as
+// real combined emphasis. CommonMark renders "\*" as a literal "*" with no
+// emphasis semantics; dropping the escape + its target from the detection
+// input keeps the heuristic aligned with what the renderer actually does.
+//
+// Known limitation: a doubled backslash escape ("\\" followed by a real
+// emphasis marker, e.g. `\\***text***`) renders as a literal backslash
+// followed by genuine combined emphasis, but this strip is not a proper
+// parser and will instead consume the second backslash as the opener for
+// another escape. That hides the real emphasis from the check, producing
+// a false negative. Practical impact is small (this shape is rare in the
+// kind of AI-Agent prompts we target) and the alternative — a full
+// CommonMark escape parser — is not worth the code surface here.
+func stripEscapedEmphasisMarkers(s string) string {
+	s = strings.ReplaceAll(s, `\*`, "")
+	s = strings.ReplaceAll(s, `\_`, "")
+	return s
+}
+
+// codeFenceOpenMarker returns the fence marker (e.g. "```" or "~~~~") if
+// line opens a fenced code block, otherwise "". Applies CommonMark §4.5
+// rules: up to 3 leading spaces are tolerated; 4+ leading spaces (or any
+// leading tab, which expands to 4 columns) make the line an indented code
+// block rather than a fence.
+func codeFenceOpenMarker(line string) string {
+	body, ok := fenceIndentOK(line)
+	if !ok {
+		return ""
+	}
+	switch {
+	case strings.HasPrefix(body, "```"):
+		return leadingRun(body, '`')
+	case strings.HasPrefix(body, "~~~"):
+		return leadingRun(body, '~')
+	}
+	return ""
+}
+
+// isCodeFenceClose reports whether line closes a fence opened with marker.
+// Per CommonMark §4.5 the closer must use the same fence character, be at
+// least as long as the opener, sit within 0..3 leading spaces, and carry
+// no info-string text.
+func isCodeFenceClose(line, marker string) bool {
+	if marker == "" {
+		return false
+	}
+	body, ok := fenceIndentOK(line)
+	if !ok {
+		return false
+	}
+	fenceChar := marker[0]
+	run := leadingRun(body, fenceChar)
+	if len(run) < len(marker) {
+		return false
+	}
+	return strings.TrimSpace(body[len(run):]) == ""
+}
+
+// fenceIndentOK returns (bodyWithoutLeadingSpaces, true) when line has
+// 0..3 leading spaces and no leading tab — i.e. the indentation is
+// permissible for a CommonMark fence. Returns ("", false) otherwise
+// (4+ leading spaces or any tab), meaning the line must be treated as
+// indented code block content rather than a fence boundary.
+func fenceIndentOK(line string) (string, bool) {
+	for i := 0; i < len(line) && i < 4; i++ {
+		switch line[i] {
+		case ' ':
+			continue
+		case '\t':
+			return "", false
+		default:
+			return line[i:], true
+		}
+	}
+	// Reached index 4 without hitting a non-space character: too indented.
+	if len(line) >= 4 {
+		return "", false
+	}
+	// Line shorter than 4 chars and all spaces — still valid (empty content).
+	return "", true
+}
+
+// leadingRun returns the longest prefix of s made up of the byte c.
+func leadingRun(s string, c byte) string {
+	i := 0
+	for i < len(s) && s[i] == c {
+		i++
+	}
+	return s[:i]
+}

shortcuts/doc/docs_update_check_test.go

@@ -0,0 +1,375 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestCheckDocsUpdateReplaceMultilineMarkdown(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		mode     string
+		markdown string
+		wantHint bool
+	}{
+		{
+			name:     "replace_range with blank line emits hint",
+			mode:     "replace_range",
+			markdown: "new paragraph\n\nsecond paragraph",
+			wantHint: true,
+		},
+		{
+			name:     "replace_all with blank line emits hint",
+			mode:     "replace_all",
+			markdown: "first\n\nsecond",
+			wantHint: true,
+		},
+		{
+			name:     "replace_range single paragraph is fine",
+			mode:     "replace_range",
+			markdown: "just a single paragraph of text",
+			wantHint: false,
+		},
+		{
+			name:     "single newline is not a paragraph break",
+			mode:     "replace_range",
+			markdown: "line one\nline two",
+			wantHint: false,
+		},
+		{
+			name:     "crlf paragraph break is also detected",
+			mode:     "replace_range",
+			markdown: "first\r\n\r\nsecond",
+			wantHint: true,
+		},
+		{
+			name:     "other modes are not flagged",
+			mode:     "insert_before",
+			markdown: "first\n\nsecond",
+			wantHint: false,
+		},
+		{
+			name:     "append mode is not flagged",
+			mode:     "append",
+			markdown: "first\n\nsecond",
+			wantHint: false,
+		},
+		{
+			name:     "empty markdown is fine",
+			mode:     "replace_range",
+			markdown: "",
+			wantHint: false,
+		},
+		{
+			// The check must ignore blank lines inside fenced code; otherwise
+			// a user replacing one block with a legitimate code sample that
+			// contains blank lines would see a spurious warning.
+			name:     "blank line inside backtick fenced code is not flagged",
+			mode:     "replace_range",
+			markdown: "```\nline1\n\nline2\n```",
+			wantHint: false,
+		},
+		{
+			name:     "blank line inside tilde fenced code is not flagged",
+			mode:     "replace_range",
+			markdown: "~~~\ncode line one\n\ncode line two\n~~~",
+			wantHint: false,
+		},
+		{
+			// Mixed prose + fenced code: any blank line in prose still wins,
+			// even if the fenced content also contains blanks.
+			name:     "blank line in prose outside fence still flags even when fence has blanks",
+			mode:     "replace_range",
+			markdown: "first paragraph\n\nsecond paragraph\n\n```\ncode\n\nmore\n```",
+			wantHint: true,
+		},
+		{
+			// Fenced code with no blank lines inside must not trip on the
+			// fence markers themselves.
+			name:     "fenced code with no blank lines does not flag",
+			mode:     "replace_range",
+			markdown: "prose before\n```go\nfmt.Println(\"hi\")\n```\nprose after",
+			wantHint: false,
+		},
+		{
+			// CommonMark §4.5: the closing fence must be ≥ opening fence length.
+			// A 4-backtick close for a 3-backtick open is a legitimate way to
+			// embed triple-backticks in a code sample; the check must see the
+			// fence as properly closed and not treat the rest of the document
+			// as still-inside-fence.
+			name:     "longer close marker closes fence correctly",
+			mode:     "replace_range",
+			markdown: "```\nsome code\n````\n\nprose paragraph after",
+			wantHint: true, // the blank line AFTER the fence is real prose
+		},
+		{
+			name:     "longer close marker still hides blank line inside fence",
+			mode:     "replace_range",
+			markdown: "```\nbefore\n\nafter\n````",
+			wantHint: false,
+		},
+		{
+			// 4+ leading spaces make the line an indented code block, not a
+			// fence open. The "fence"-looking line is code content; the
+			// surrounding blank must still be detected.
+			name:     "four-space indented fence-like line is not a fence open",
+			mode:     "replace_range",
+			markdown: "first paragraph\n\n    ```\n    code\n    ```",
+			wantHint: true,
+		},
+		{
+			// A tab in the leading whitespace is always ≥4 columns and thus
+			// forces indented-code-block semantics.
+			name:     "tab-indented fence-like line is not a fence open",
+			mode:     "replace_range",
+			markdown: "first paragraph\n\n\t```\n\tcode\n\t```",
+			wantHint: true,
+		},
+		{
+			// 3 leading spaces is still within the fence-tolerance window.
+			name:     "three-space indented fence is still a fence",
+			mode:     "replace_range",
+			markdown: "   ```\ncode\n\nmore\n   ```",
+			wantHint: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := checkDocsUpdateReplaceMultilineMarkdown(tt.mode, tt.markdown)
+			hasHint := got != ""
+			if hasHint != tt.wantHint {
+				t.Fatalf("checkDocsUpdateReplaceMultilineMarkdown(%q, %q) = %q, wantHint=%v",
+					tt.mode, tt.markdown, got, tt.wantHint)
+			}
+			if tt.wantHint && (!strings.Contains(got, "delete_range") || !strings.Contains(got, "insert_before")) {
+				t.Errorf("hint should suggest delete_range/insert_before remediation, got: %s", got)
+			}
+		})
+	}
+}
+
+func TestCheckDocsUpdateBoldItalic(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		input    string
+		wantHint bool
+	}{
+		{
+			name:     "triple asterisks flagged",
+			input:    "a ***key insight*** here",
+			wantHint: true,
+		},
+		{
+			name:     "triple asterisks single char flagged",
+			input:    "a ***X*** here",
+			wantHint: true,
+		},
+		{
+			name:     "bold wrapping underscore italic flagged",
+			input:    "note: **_important_** detail",
+			wantHint: true,
+		},
+		{
+			name:     "underscore wrapping double asterisk flagged",
+			input:    "note: _**important**_ detail",
+			wantHint: true,
+		},
+		{
+			name:     "plain bold is fine",
+			input:    "this is **bold** text",
+			wantHint: false,
+		},
+		{
+			name:     "plain italic is fine",
+			input:    "this is *italic* or _italic_ text",
+			wantHint: false,
+		},
+		{
+			name:     "horizontal rule is not flagged",
+			input:    "paragraph\n\n---\n\nnext",
+			wantHint: false,
+		},
+		{
+			name:     "bold followed by italic with space is not flagged",
+			input:    "**bold** and *italic*",
+			wantHint: false,
+		},
+		{
+			name:     "empty input is fine",
+			input:    "",
+			wantHint: false,
+		},
+		{
+			// The emphasis check must not fire on literal Markdown samples
+			// inside a fenced code block — the canonical use case is docs
+			// authors pasting tutorials that demonstrate these exact patterns.
+			name:     "triple asterisks inside backtick fenced code is not flagged",
+			input:    "example:\n```\nthe shape ***keyword*** downgrades\n```",
+			wantHint: false,
+		},
+		{
+			name:     "underscore-bold inside fenced code is not flagged",
+			input:    "example:\n```markdown\nuse **_strong italic_** carefully\n```",
+			wantHint: false,
+		},
+		{
+			name:     "bold-underscore inside fenced code is not flagged",
+			input:    "example:\n~~~\n_**outside-underscore**_ is a bad shape\n~~~",
+			wantHint: false,
+		},
+		{
+			name:     "triple asterisks inside inline code span is not flagged",
+			input:    "the literal `***text***` marker is just a sample",
+			wantHint: false,
+		},
+		{
+			name:     "underscore-bold inside inline code is not flagged",
+			input:    "the shape `**_italic_**` would downgrade, but only if it were real",
+			wantHint: false,
+		},
+		{
+			name:     "escaped triple asterisks rendered as literal text is not flagged",
+			input:    `the literal \***text*** with escaped opener`,
+			wantHint: false,
+		},
+		{
+			name:     "escaped bold inside underscore-italic is not flagged",
+			input:    `shape \*\*_text_\*\* is literal, not emphasis`,
+			wantHint: false,
+		},
+		{
+			// Real emphasis outside the code span must still be detected —
+			// the strip step must not over-sanitize.
+			name:     "real triple asterisks outside inline code still flags",
+			input:    "real ***strong*** and literal `***keyword***` — the first one counts",
+			wantHint: true,
+		},
+		{
+			name:     "real triple asterisks outside fenced code still flags",
+			input:    "real ***strong***\n\n```\nliteral ***keyword*** in code\n```",
+			wantHint: true,
+		},
+		// --- Triple-underscore combined emphasis: ___text___ ---
+		{
+			name:     "triple underscores flagged",
+			input:    "a ___key insight___ here",
+			wantHint: true,
+		},
+		{
+			name:     "triple underscores single char flagged",
+			input:    "a ___X___ here",
+			wantHint: true,
+		},
+		{
+			name:     "triple underscores inside fenced code not flagged",
+			input:    "sample:\n```\nuse ___keyword___ carefully\n```",
+			wantHint: false,
+		},
+		{
+			name:     "triple underscores inside inline code not flagged",
+			input:    "the literal `___phrase___` marker",
+			wantHint: false,
+		},
+		{
+			name:     "escaped triple underscores not flagged",
+			input:    `literal \___phrase___ with escaped opener`,
+			wantHint: false,
+		},
+		// --- Underscore-bold wrapping asterisk-italic: __*text*__ ---
+		{
+			name:     "underscore-bold wrapping asterisk-italic flagged",
+			input:    "note: __*important*__ text",
+			wantHint: true,
+		},
+		{
+			name:     "underscore-bold wrapping asterisk-italic inside fenced code not flagged",
+			input:    "```\nnote: __*important*__ sample\n```",
+			wantHint: false,
+		},
+		{
+			name:     "underscore-bold wrapping asterisk-italic inside inline code not flagged",
+			input:    "literal `__*important*__` marker",
+			wantHint: false,
+		},
+		// --- Asterisk-italic wrapping underscore-bold: *__text__* ---
+		{
+			name:     "asterisk-italic wrapping underscore-bold flagged",
+			input:    "note: *__phrase__* text",
+			wantHint: true,
+		},
+		{
+			name:     "asterisk-italic wrapping underscore-bold inside fenced code not flagged",
+			input:    "```md\nnote: *__phrase__* sample\n```",
+			wantHint: false,
+		},
+		// --- Positive tests: real emphasis in prose coexisting with fake in code ---
+		{
+			// Underscore-variant in prose must still fire when an asterisk
+			// variant appears inside a code span — verifies the strip does
+			// not over-sanitize across the six regex alternatives.
+			name:     "real triple underscores outside inline code still flag when asterisk variant is in code",
+			input:    "real ___strong___ and literal `***shape***` in code",
+			wantHint: true,
+		},
+		{
+			// Longer close fence closes properly; real ***emphasis*** after
+			// the fence must fire.
+			name:     "real emphasis after a fence closed by longer marker still flags",
+			input:    "```\nliteral ***phrase*** in code\n````\n\nand then real ***phrase*** after",
+			wantHint: true,
+		},
+		{
+			// 4-space indented "```" is an indented code block, not a fence
+			// open. The fence helper should refuse it; emphasis outside the
+			// (non-existent) fence must still be detected.
+			name:     "four-space indented fence-like line does not open a fence for the emphasis check",
+			input:    "prose\n\n    ```\n    not a fence\n    ```\n\nreal ***strong*** here",
+			wantHint: true,
+		},
+		{
+			// 3-space indented fence is valid per CommonMark. Emphasis inside
+			// must be sanitized away, so the check must not fire.
+			name:     "three-space indented fence still hides triple-asterisk inside",
+			input:    "   ```\n   literal ***text*** inside\n   ```",
+			wantHint: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := checkDocsUpdateBoldItalic(tt.input)
+			hasHint := got != ""
+			if hasHint != tt.wantHint {
+				t.Fatalf("checkDocsUpdateBoldItalic(%q) = %q, wantHint=%v", tt.input, got, tt.wantHint)
+			}
+		})
+	}
+}
+
+func TestDocsUpdateWarningsAggregates(t *testing.T) {
+	t.Parallel()
+
+	// Both flags trigger: replace_range with blank line AND triple-asterisk.
+	warnings := docsUpdateWarnings("replace_range", "***opening***\n\nsecond paragraph")
+	if len(warnings) != 2 {
+		t.Fatalf("expected 2 warnings, got %d: %v", len(warnings), warnings)
+	}
+}
+
+func TestDocsUpdateWarningsEmpty(t *testing.T) {
+	t.Parallel()
+
+	// Clean markdown in a non-replace mode produces zero warnings.
+	warnings := docsUpdateWarnings("insert_before", "plain paragraph text")
+	if len(warnings) != 0 {
+		t.Fatalf("expected no warnings, got: %v", warnings)
+	}
+}

shortcuts/doc/docs_update_test.go

@@ -3,12 +3,9 @@
 package doc
 
 import (
-	"context"
+	"reflect"
 	"strings"
 	"testing"
-
-	"github.com/larksuite/cli/shortcuts/common"
-	"github.com/spf13/cobra"
 )
 
 // ── V2 tests ──
@@ -34,102 +31,199 @@ func TestValidCommandsV2(t *testing.T) {
 	}
 }
 
-func TestDocsUpdateDryRunAcceptsDeprecatedAPIVersionValues(t *testing.T) {
-	for _, apiVersion := range []string{"v1", "v2"} {
-		t.Run(apiVersion, func(t *testing.T) {
-			t.Parallel()
+// ── V1 tests ──
 
-			runtime := newUpdateShortcutTestRuntime(t, apiVersion, nil)
-			if err := validateUpdateV2(context.Background(), runtime); err != nil {
-				t.Fatalf("validateUpdateV2() error = %v", err)
-			}
+func TestSelectionRequiredMessageV1ReplaceAllSuggestsOverwrite(t *testing.T) {
+	t.Parallel()
 
-			dry := decodeDocDryRun(t, DocsUpdate.DryRun(context.Background(), runtime))
-			if len(dry.API) != 1 {
-				t.Fatalf("expected 1 dry-run API call, got %d", len(dry.API))
-			}
-			if got, want := dry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnUpdateDryRun"; got != want {
-				t.Fatalf("dry-run URL = %q, want %q", got, want)
-			}
-			if got, want := dry.API[0].Body["command"], "block_insert_after"; got != want {
-				t.Fatalf("dry-run command = %#v, want %q", got, want)
-			}
-			if got, want := dry.API[0].Body["block_id"], "-1"; got != want {
-				t.Fatalf("dry-run block_id = %#v, want %q", got, want)
-			}
-		})
+	msg := selectionRequiredMessageV1("replace_all")
+	for _, needle := range []string{
+		"--replace_all mode requires --selection-with-ellipsis or --selection-by-title",
+		"replace the entire document body",
+		"--mode overwrite",
+	} {
+		if !strings.Contains(msg, needle) {
+			t.Fatalf("message missing %q: %s", needle, msg)
+		}
 	}
 }
 
-func TestDocsUpdateRejectsLegacyFlags(t *testing.T) {
+func TestSelectionRequiredMessageV1OtherModesDoNotSuggestOverwrite(t *testing.T) {
+	t.Parallel()
+
+	msg := selectionRequiredMessageV1("replace_range")
+	if strings.Contains(msg, "--mode overwrite") {
+		t.Fatalf("replace_range message should not suggest overwrite: %s", msg)
+	}
+	if !strings.Contains(msg, "--replace_range mode requires --selection-with-ellipsis or --selection-by-title") {
+		t.Fatalf("unexpected message: %s", msg)
+	}
+}
+
+func TestIsWhiteboardCreateMarkdown(t *testing.T) {
+	t.Run("blank whiteboard tags", func(t *testing.T) {
+		markdown := "<whiteboard type=\"blank\"></whiteboard>\n<whiteboard type=\"blank\"></whiteboard>"
+		if !isWhiteboardCreateMarkdown(markdown) {
+			t.Fatalf("expected blank whiteboard markdown to be treated as whiteboard creation")
+		}
+	})
+
+	t.Run("mermaid code block", func(t *testing.T) {
+		markdown := "```mermaid\ngraph TD\nA-->B\n```"
+		if !isWhiteboardCreateMarkdown(markdown) {
+			t.Fatalf("expected mermaid markdown to be treated as whiteboard creation")
+		}
+	})
+
+	t.Run("plain markdown", func(t *testing.T) {
+		markdown := "## plain text"
+		if isWhiteboardCreateMarkdown(markdown) {
+			t.Fatalf("did not expect plain markdown to be treated as whiteboard creation")
+		}
+	})
+}
+
+func TestCheckOverwriteResourceBlocks(t *testing.T) {
+	t.Parallel()
+
 	tests := []struct {
 		name     string
-		setFlags map[string]string
-		want     []string
+		markdown string
+		wantWarn bool
+		wantSubs []string
 	}{
 		{
-			name:     "legacy mode",
-			setFlags: map[string]string{"mode": "overwrite"},
-			want: []string{
-				"docs +update is v2-only",
-				"the old v1 interface has been shut down",
-				"legacy v1 flag(s) --mode are no longer supported",
-				"--mode -> use --command",
-				"lark-cli skills read lark-doc references/lark-doc-update.md",
-				"lark-cli skills read lark-doc references/lark-doc-xml.md",
-				"lark-cli skills read lark-doc references/lark-doc-md.md",
-				"follow the latest format rules",
-				"MUST NOT grep/open local SKILL.md files",
-				"lark-cli docs +update --help",
-			},
+			name:     "empty markdown is clean",
+			markdown: "",
+			wantWarn: false,
+		},
+		{
+			name:     "plain prose is clean",
+			markdown: "## Heading\n\nsome text",
+			wantWarn: false,
+		},
+		{
+			name:     "single whiteboard triggers warning",
+			markdown: `<whiteboard token="abc123"/>`,
+			wantWarn: true,
+			wantSubs: []string{"1 whiteboard block", "overwrite"},
+		},
+		{
+			name:     "multiple whiteboards counted",
+			markdown: "<whiteboard token=\"a\"/>\n<whiteboard token=\"b\"/>",
+			wantWarn: true,
+			wantSubs: []string{"2 whiteboard blocks"},
+		},
+		{
+			name:     "single file attachment triggers warning",
+			markdown: `<file token="tok" name="report.pdf"/>`,
+			wantWarn: true,
+			wantSubs: []string{"1 file attachment block"},
+		},
+		{
+			name:     "multiple file attachments counted",
+			markdown: "<file token=\"a\"/>\n<file token=\"b\"/>\n<file token=\"c\"/>",
+			wantWarn: true,
+			wantSubs: []string{"3 file attachment blocks"},
+		},
+		{
+			name:     "whiteboard and file together both counted",
+			markdown: "<whiteboard token=\"wb\"/>\n<file token=\"f\"/>",
+			wantWarn: true,
+			wantSubs: []string{"1 whiteboard block", "1 file attachment block"},
 		},
 	}
-
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
-
-			runtime := newUpdateShortcutTestRuntime(t, "", tt.setFlags)
-			err := validateUpdateV2(context.Background(), runtime)
-			if err == nil {
-				t.Fatal("expected v2-only validation error")
+			got := checkOverwriteResourceBlocks(tt.markdown)
+			if (got != "") != tt.wantWarn {
+				t.Fatalf("checkOverwriteResourceBlocks(%q) = %q, wantWarn=%v", tt.markdown, got, tt.wantWarn)
 			}
-			for _, want := range tt.want {
-				if !strings.Contains(err.Error(), want) {
-					t.Fatalf("error missing %q: %v", want, err)
+			for _, sub := range tt.wantSubs {
+				if !strings.Contains(got, sub) {
+					t.Errorf("expected warning to contain %q, got: %s", sub, got)
 				}
 			}
 		})
 	}
 }
 
-func newUpdateShortcutTestRuntime(t *testing.T, apiVersion string, setFlags map[string]string) *common.RuntimeContext {
-	t.Helper()
+func TestNormalizeWhiteboardResult(t *testing.T) {
+	t.Run("adds empty board_tokens when whiteboard creation response omits it", func(t *testing.T) {
+		result := map[string]interface{}{
+			"success": true,
+		}
 
-	cmd := &cobra.Command{Use: "+update"}
-	cmd.Flags().String("api-version", "", "")
-	cmd.Flags().String("doc", "doxcnUpdateDryRun", "")
-	cmd.Flags().String("doc-format", "xml", "")
-	cmd.Flags().String("command", "append", "")
-	cmd.Flags().Int("revision-id", -1, "")
-	cmd.Flags().String("content", "<p>hello</p>", "")
-	cmd.Flags().String("pattern", "", "")
-	cmd.Flags().String("block-id", "", "")
-	cmd.Flags().String("src-block-ids", "", "")
-	cmd.Flags().String("mode", "", "")
-	cmd.Flags().String("markdown", "", "")
-	cmd.Flags().String("selection-with-ellipsis", "", "")
-	cmd.Flags().String("selection-by-title", "", "")
-	cmd.Flags().String("new-title", "", "")
-	if apiVersion != "" {
-		if err := cmd.Flags().Set("api-version", apiVersion); err != nil {
-			t.Fatalf("set api-version: %v", err)
+		normalizeWhiteboardResult(result, "<whiteboard type=\"blank\"></whiteboard>")
+
+		got, ok := result["board_tokens"].([]string)
+		if !ok {
+			t.Fatalf("expected board_tokens to be []string, got %T", result["board_tokens"])
 		}
-	}
-	for name, value := range setFlags {
-		if err := cmd.Flags().Set(name, value); err != nil {
-			t.Fatalf("set %s: %v", name, err)
+		if len(got) != 0 {
+			t.Fatalf("expected empty board_tokens, got %#v", got)
 		}
-	}
-	return common.TestNewRuntimeContext(cmd, nil)
+	})
+
+	t.Run("normalizes board_tokens to string slice", func(t *testing.T) {
+		result := map[string]interface{}{
+			"board_tokens": []interface{}{"board_1", "board_2"},
+		}
+
+		normalizeWhiteboardResult(result, "<whiteboard type=\"blank\"></whiteboard>")
+
+		want := []string{"board_1", "board_2"}
+		got, ok := result["board_tokens"].([]string)
+		if !ok {
+			t.Fatalf("expected board_tokens to be []string, got %T", result["board_tokens"])
+		}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("board_tokens mismatch: got %#v want %#v", got, want)
+		}
+	})
+
+	t.Run("leaves non whiteboard response unchanged", func(t *testing.T) {
+		result := map[string]interface{}{
+			"success": true,
+		}
+
+		normalizeWhiteboardResult(result, "## plain text")
+
+		if _, ok := result["board_tokens"]; ok {
+			t.Fatalf("did not expect board_tokens for non-whiteboard markdown")
+		}
+	})
+}
+
+func TestValidateSelectionByTitleV1(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		title   string
+		wantErr bool
+		errSub  string
+	}{
+		{name: "empty title is valid", title: "", wantErr: false},
+		{name: "single heading is valid", title: "## Section", wantErr: false},
+		{name: "h1 heading is valid", title: "# Top", wantErr: false},
+		{name: "deep heading is valid", title: "### Sub-section", wantErr: false},
+		{name: "missing hash prefix is invalid", title: "No hash", wantErr: true, errSub: "'#'"},
+		{name: "multiline title is invalid", title: "## First\n## Second", wantErr: true, errSub: "single"},
+		{name: "title with embedded carriage return is invalid", title: "## Title\r## Next", wantErr: true, errSub: "single"},
+		{name: "leading-space heading is valid after trim", title: "  ## Section", wantErr: false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			err := validateSelectionByTitleV1(tt.title)
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("validateSelectionByTitleV1(%q) error = %v, wantErr = %v", tt.title, err, tt.wantErr)
+			}
+			if tt.wantErr && tt.errSub != "" && !strings.Contains(err.Error(), tt.errSub) {
+				t.Errorf("expected error to contain %q, got: %v", tt.errSub, err)
+			}
+		})
+	}
 }

shortcuts/doc/docs_update_v2.go

@@ -24,13 +24,13 @@ var validCommandsV2 = map[string]bool{
 // v2UpdateFlags returns the flag definitions for the v2 (OpenAPI) update path.
 func v2UpdateFlags() []common.Flag {
 	return []common.Flag{
-		{Name: "command", Desc: "operation; requirements: str_replace(--pattern), block_delete(--block-id), block_insert_after/block_replace(--block-id,--content), block_copy_insert_after/block_move_after(--block-id,--src-block-ids), overwrite/append(--content)", Enum: validCommandsV2Keys()},
-		{Name: "doc-format", Desc: "content format for --content; xml is default for precise rich edits, markdown for user-provided Markdown or plain append/overwrite", Default: "xml", Enum: []string{"xml", "markdown"}},
-		{Name: "content", Desc: "replacement or inserted content; XML by default or Markdown when --doc-format markdown; empty with str_replace deletes match. " + docsContentSkillHelp + "; use --help for the latest command flags", Input: []string{common.File, common.Stdin}},
-		{Name: "pattern", Desc: "str_replace match pattern; XML mode is inline text, Markdown mode can match multiline text"},
-		{Name: "block-id", Desc: "target anchor/block id for block operations; -1 means document end where supported"},
-		{Name: "src-block-ids", Desc: "comma-separated source block ids for block_copy_insert_after and block_move_after"},
-		{Name: "revision-id", Desc: "base revision id; -1 means latest", Type: "int", Default: "-1"},
+		{Name: "command", Desc: "operation: str_replace | block_delete | block_insert_after | block_copy_insert_after | block_replace | block_move_after | overwrite | append", Hidden: true, Enum: validCommandsV2Keys()},
+		{Name: "doc-format", Desc: "content format (prefer XML)", Hidden: true, Default: "xml", Enum: []string{"xml", "markdown"}},
+		{Name: "content", Desc: "new content (XML or Markdown)", Hidden: true, Input: []string{common.File, common.Stdin}},
+		{Name: "pattern", Desc: "regex pattern for str_replace", Hidden: true},
+		{Name: "block-id", Desc: "target block ID for block_* operations", Hidden: true},
+		{Name: "src-block-ids", Desc: "source block IDs (comma-separated) for block_copy_insert_after / block_move_after", Hidden: true},
+		{Name: "revision-id", Desc: "base revision (-1 = latest)", Hidden: true, Type: "int", Default: "-1"},
 	}
 }
 
@@ -39,9 +39,6 @@ func validCommandsV2Keys() []string {
 }
 
 func validateUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
-	if err := validateDocsV2Only(runtime, "+update", docsUpdateLegacyFlags()); err != nil {
-		return err
-	}
 	if _, err := parseDocumentRef(runtime.Str("doc")); err != nil {
 		return common.FlagErrorf("invalid --doc: %v", err)
 	}

shortcuts/doc/markdown_fix.go

@@ -0,0 +1,649 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"fmt"
+	"io"
+	"regexp"
+	"strings"
+	"unicode"
+	"unicode/utf8"
+)
+
+// fixExportedMarkdown applies post-processing to Lark-exported Markdown to
+// improve round-trip fidelity on re-import:
+//
+//  1. fixBoldSpacing: removes trailing whitespace before closing ** / *,
+//     and strips redundant ** from ATX headings. Applied only outside fenced
+//     code blocks, and skips inline code spans.
+//
+//  2. normalizeNestedListIndentation: rewrites space-pair-indented nested list
+//     markers to tab-indented markers. This avoids nested ordered list items
+//     being flattened or interpreted as plain text/code on re-import.
+//
+//  3. fixSetextAmbiguity: inserts a blank line before any "---" that immediately
+//     follows a non-empty line, preventing it from being parsed as a Setext H2.
+//     Applied only outside fenced code blocks.
+//
+//  4. fixBlockquoteHardBreaks: inserts a blank blockquote line (">") between
+//     consecutive blockquote content lines so create-doc preserves line breaks.
+//     Applied only outside fenced code blocks.
+//
+//  5. fixTopLevelSoftbreaks: inserts a blank line between adjacent non-empty
+//     lines at the top level and inside content containers (callout,
+//     quote-container, lark-td). Code fences are left untouched, and
+//     consecutive list items / continuations are not separated.
+//
+//  6. fixCalloutEmoji: replaces named emoji aliases (e.g. emoji="warning") with
+//     actual Unicode emoji characters that create-doc understands. Applied only
+//     outside fenced code blocks.
+func fixExportedMarkdown(md string) string {
+	md = applyOutsideCodeFences(md, fixBoldSpacing)
+	md = applyOutsideCodeFences(md, normalizeNestedListIndentation)
+	md = applyOutsideCodeFences(md, fixSetextAmbiguity)
+	md = applyOutsideCodeFences(md, fixBlockquoteHardBreaks)
+	md = fixTopLevelSoftbreaks(md)
+	md = applyOutsideCodeFences(md, fixCalloutEmoji)
+	// Collapse runs of 3+ consecutive newlines into exactly 2 (one blank line),
+	// but only outside fenced code blocks to preserve intentional blank lines in code.
+	md = applyOutsideCodeFences(md, func(s string) string {
+		for strings.Contains(s, "\n\n\n") {
+			s = strings.ReplaceAll(s, "\n\n\n", "\n\n")
+		}
+		return s
+	})
+	md = strings.TrimRight(md, "\n") + "\n"
+	return md
+}
+
+// applyOutsideCodeFences applies fn only to content outside fenced code blocks.
+// Lines inside fenced code blocks (``` ... ```) are passed through unchanged,
+// preventing transforms from corrupting literal code content.
+func applyOutsideCodeFences(md string, fn func(string) string) string {
+	lines := strings.Split(md, "\n")
+	var out []string
+	var chunk []string
+	inCode := false
+
+	flush := func() {
+		if len(chunk) == 0 {
+			return
+		}
+		out = append(out, strings.Split(fn(strings.Join(chunk, "\n")), "\n")...)
+		chunk = chunk[:0]
+	}
+
+	for _, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "```") {
+			if !inCode {
+				flush()
+				inCode = true
+			} else if trimmed == "```" {
+				inCode = false
+			}
+			out = append(out, line)
+			continue
+		}
+		if inCode {
+			out = append(out, line)
+		} else {
+			chunk = append(chunk, line)
+		}
+	}
+	flush()
+	return strings.Join(out, "\n")
+}
+
+// fixBlockquoteHardBreaks inserts a blank blockquote line (">") between
+// consecutive blockquote content lines. This forces each line into its own
+// paragraph within the blockquote, so MCP create-doc preserves line breaks
+// instead of collapsing them into a single paragraph.
+//
+// Before: "> line1\n> line2"  →  After: "> line1\n>\n> line2"
+func fixBlockquoteHardBreaks(md string) string {
+	lines := strings.Split(md, "\n")
+	out := make([]string, 0, len(lines)*2)
+	for i, line := range lines {
+		out = append(out, line)
+		if strings.HasPrefix(line, "> ") && i+1 < len(lines) && strings.HasPrefix(lines[i+1], "> ") {
+			out = append(out, ">")
+		}
+	}
+	return strings.Join(out, "\n")
+}
+
+// fixBoldSpacing normalizes emphasis markers exported by Lark while preserving
+// inline code spans:
+//
+//  1. Removes leading whitespace after opening ** and * delimiters:
+//     "** text**" → "**text**", "* text*" → "*text*"
+//
+//  2. Removes trailing whitespace before closing ** and * delimiters:
+//     "**text **" → "**text**", "*text *" → "*text*"
+//
+//  3. Removes redundant bold around an entire ATX heading:
+//     "# **text**" → "# text"
+//
+// The bold and italic spacing fixes only run on non-code segments so literal
+// code content is left unchanged.
+var (
+	// headingBoldRe uses [^*]+ (no asterisks) to avoid mismatching headings
+	// that contain multiple disjoint bold spans such as "# **foo** and **bar**".
+	headingBoldRe = regexp.MustCompile(`(?m)^(#{1,6})\s+\*\*([^*]+)\*\*\s*$`)
+)
+
+func fixBoldSpacing(md string) string {
+	lines := strings.Split(md, "\n")
+	for i, line := range lines {
+		lines[i] = fixBoldSpacingLine(line)
+	}
+	md = strings.Join(lines, "\n")
+	md = headingBoldRe.ReplaceAllString(md, "$1 $2")
+	return md
+}
+
+// atxHeadingRe matches ATX heading lines (# ... through ###### ...).
+var atxHeadingRe = regexp.MustCompile(`^#{1,6}\s`)
+
+// scanInlineCodeSpans returns the byte ranges [start, end) of all inline code
+// spans in line. It handles multi-backtick delimiters (e.g. “ `foo` “) by
+// finding the opening run of N backticks and searching for the next identical
+// run to close the span, per CommonMark spec §6.1.
+func scanInlineCodeSpans(line string) [][2]int {
+	var spans [][2]int
+	i := 0
+	for i < len(line) {
+		if line[i] != '`' {
+			i++
+			continue
+		}
+		// Count the opening backtick run.
+		start := i
+		for i < len(line) && line[i] == '`' {
+			i++
+		}
+		delim := line[start:i] // e.g. "`" or "``" or "```"
+		// Search for the closing run of the same length.
+		j := i
+		for j <= len(line)-len(delim) {
+			if line[j] == '`' {
+				k := j
+				for k < len(line) && line[k] == '`' {
+					k++
+				}
+				if k-j == len(delim) {
+					spans = append(spans, [2]int{start, k})
+					i = k
+					break
+				}
+				j = k // skip this backtick run and keep searching
+			} else {
+				j++
+			}
+		}
+		// No closing delimiter found — not a code span, continue.
+	}
+	return spans
+}
+
+// fixBoldSpacingLine applies bold/italic trailing-space fixes to a single line,
+// skipping content inside inline code spans to avoid corrupting literal code.
+// ATX heading lines are also skipped here because headingBoldRe in fixBoldSpacing
+// handles them separately, keeping heading-only normalization isolated from the
+// inline emphasis spacing scanner below.
+func fixBoldSpacingLine(line string) string {
+	if atxHeadingRe.MatchString(line) {
+		return line
+	}
+	spans := scanInlineCodeSpans(line)
+	if len(spans) == 0 {
+		return fixEmphasisSpacingSegment(line)
+	}
+	var sb strings.Builder
+	pos := 0
+	for _, loc := range spans {
+		// Process the non-code segment before this inline code span.
+		seg := line[pos:loc[0]]
+		sb.WriteString(fixEmphasisSpacingSegment(seg))
+		// Preserve inline code span as-is.
+		sb.WriteString(line[loc[0]:loc[1]])
+		pos = loc[1]
+	}
+	// Remaining non-code segment after the last code span.
+	sb.WriteString(fixEmphasisSpacingSegment(line[pos:]))
+	return sb.String()
+}
+
+// fixEmphasisSpacingSegment trims only the whitespace immediately inside simple
+// *...* and **...** spans. It deliberately ignores runs of 3+ asterisks and
+// any candidate whose payload contains another asterisk so nested emphasis-like
+// text remains untouched. When both inner sides contain whitespace, single-rune
+// payloads are preserved as literal text (for example "* x *" and "** x **").
+func fixEmphasisSpacingSegment(seg string) string {
+	if !strings.Contains(seg, "*") {
+		return seg
+	}
+
+	var sb strings.Builder
+	pos := 0
+	for pos < len(seg) {
+		openStart, openEnd, ok := nextAsteriskRun(seg, pos)
+		if !ok {
+			sb.WriteString(seg[pos:])
+			break
+		}
+
+		sb.WriteString(seg[pos:openStart])
+
+		markerLen := openEnd - openStart
+		if markerLen != 1 && markerLen != 2 {
+			sb.WriteString(seg[openStart:openEnd])
+			pos = openEnd
+			continue
+		}
+
+		closeStart, closeEnd, ok := nextAsteriskRun(seg, openEnd)
+		if !ok || closeEnd-closeStart != markerLen {
+			sb.WriteString(seg[openStart:openEnd])
+			pos = openEnd
+			continue
+		}
+
+		payload := seg[openEnd:closeStart]
+		normalized, shouldNormalize := normalizeEmphasisPayload(payload)
+		if !shouldNormalize {
+			sb.WriteString(seg[openStart:closeEnd])
+			pos = closeEnd
+			continue
+		}
+
+		marker := seg[openStart:openEnd]
+		sb.WriteString(marker)
+		sb.WriteString(normalized)
+		sb.WriteString(marker)
+		pos = closeEnd
+	}
+	return sb.String()
+}
+
+func nextAsteriskRun(s string, start int) (runStart, runEnd int, ok bool) {
+	for i := start; i < len(s); i++ {
+		if s[i] != '*' {
+			continue
+		}
+		j := i
+		for j < len(s) && s[j] == '*' {
+			j++
+		}
+		return i, j, true
+	}
+	return 0, 0, false
+}
+
+func normalizeEmphasisPayload(payload string) (string, bool) {
+	trimmedLeft := strings.TrimLeftFunc(payload, unicode.IsSpace)
+	trimmed := strings.TrimRightFunc(trimmedLeft, unicode.IsSpace)
+	if trimmed == "" {
+		return payload, false
+	}
+
+	hasLeadingSpace := len(trimmedLeft) != len(payload)
+	hasTrailingSpace := len(trimmed) != len(trimmedLeft)
+	if !hasLeadingSpace && !hasTrailingSpace {
+		return payload, true
+	}
+
+	if hasLeadingSpace && hasTrailingSpace && utf8.RuneCountInString(trimmed) == 1 {
+		return payload, false
+	}
+	return trimmed, true
+}
+
+var setextRe = regexp.MustCompile(`(?m)^([^\n]+)\n(-{3,}\s*$)`)
+
+func fixSetextAmbiguity(md string) string {
+	return setextRe.ReplaceAllString(md, "$1\n\n$2")
+}
+
+// calloutTypeColors maps the semantic type= shorthand to a recommended
+// [background-color, border-color] pair for Feishu callout blocks.
+// Used only for hint messages — the Markdown itself is never rewritten.
+var calloutTypeColors = map[string][2]string{
+	"warning":   {"light-yellow", "yellow"},
+	"caution":   {"light-orange", "orange"},
+	"note":      {"light-blue", "blue"},
+	"info":      {"light-blue", "blue"},
+	"tip":       {"light-green", "green"},
+	"success":   {"light-green", "green"},
+	"check":     {"light-green", "green"},
+	"error":     {"light-red", "red"},
+	"danger":    {"light-red", "red"},
+	"important": {"light-purple", "purple"},
+}
+
+// calloutOpenTagRe matches a <callout …> opening tag.
+var calloutOpenTagRe = regexp.MustCompile(`<callout(\s[^>]*)?>`)
+
+// calloutTypeAttrRe extracts the value of a type= attribute (single or
+// double quoted) from a callout opening tag's attribute string. The
+// (?:^|\s) anchor instead of \b is intentional: \b sits at any
+// word/non-word boundary, and `-` is a non-word character, so
+// `\btype=` would also match the suffix of `data-type=` and yield a
+// bogus type lookup. Anchoring on start-of-string-or-whitespace
+// requires a real attribute separator before the name.
+var calloutTypeAttrRe = regexp.MustCompile(`(?:^|\s)type=(?:"([^"]*)"|'([^']*)')`)
+
+// calloutBackgroundColorAttrRe matches a background-color= attribute
+// name with optional whitespace around the equals sign, so forms like
+// `background-color="..."` and `background-color = "..."` are both
+// accepted. Same (?:^|\s) anchor as calloutTypeAttrRe, for the same
+// reason: `data-background-color="..."` must not look like a present
+// background-color and silently suppress the hint.
+var calloutBackgroundColorAttrRe = regexp.MustCompile(`(?:^|\s)background-color\s*=`)
+
+// WarnCalloutType scans md for callout tags that carry a type= attribute but
+// no background-color= attribute, then writes a hint line to w for each one
+// suggesting the explicit Feishu color attributes to use instead.
+//
+// Callout tags inside fenced code blocks (``` or ~~~) are skipped — they
+// are documentation samples, not real callouts the user wants Feishu to
+// render. Fence detection uses the shared codeFenceOpenMarker /
+// isCodeFenceClose helpers so both backtick and tilde fences are handled
+// (matching CommonMark §4.5).
+//
+// The Markdown is not modified — the caller is responsible for acting on
+// the hints or ignoring them. This keeps the create/update path
+// transparent: user input reaches create-doc exactly as written.
+func WarnCalloutType(md string, w io.Writer) {
+	fenceMarker := ""
+	for _, line := range strings.Split(md, "\n") {
+		if fenceMarker != "" {
+			// Inside a fenced block — skip everything until the matching
+			// closer. Code samples that show literal <callout type=...>
+			// must not produce a phantom hint.
+			if isCodeFenceClose(line, fenceMarker) {
+				fenceMarker = ""
+			}
+			continue
+		}
+		if marker := codeFenceOpenMarker(line); marker != "" {
+			fenceMarker = marker
+			continue
+		}
+		scanCalloutTagsForWarning(line, w)
+	}
+}
+
+// scanCalloutTagsForWarning emits a hint to w for every <callout type="...">
+// tag in s that lacks an explicit background-color= attribute. Pulled out
+// of WarnCalloutType so the line walker only handles fence state and the
+// per-tag scan is its own readable unit.
+//
+// The previous implementation routed the tag iteration through
+// calloutOpenTagRe.ReplaceAllStringFunc with a callback that always
+// returned the original tag and threw the rebuilt string away — using a
+// rewrite primitive purely for its iteration side-effect, plus a second
+// regex execution to recover the capture groups inside the callback.
+// FindAllStringSubmatch hands us both the iteration and the groups in one
+// pass, no allocation thrown away.
+func scanCalloutTagsForWarning(s string, w io.Writer) {
+	for _, m := range calloutOpenTagRe.FindAllStringSubmatch(s, -1) {
+		attrs := m[1]
+		// Skip tags that already carry an explicit background-color.
+		if calloutBackgroundColorAttrRe.MatchString(attrs) {
+			continue
+		}
+		parts := calloutTypeAttrRe.FindStringSubmatch(attrs)
+		if len(parts) < 3 {
+			continue // no type= attribute
+		}
+		// parts[1] is the double-quoted capture, parts[2] is single-quoted.
+		typeName := parts[1]
+		if typeName == "" {
+			typeName = parts[2]
+		}
+		colors, ok := calloutTypeColors[typeName]
+		if !ok {
+			continue // unknown type — no hint to give
+		}
+		fmt.Fprintf(w,
+			"hint: callout type=%q has no background-color; consider: background-color=%q border-color=%q\n",
+			typeName, colors[0], colors[1])
+	}
+}
+
+// calloutEmojiAliases maps named emoji strings that fetch-doc emits to actual
+// Unicode emoji characters that create-doc accepts.
+var calloutEmojiAliases = map[string]string{
+	"warning":      "⚠️",
+	"note":         "📝",
+	"tip":          "💡",
+	"info":         "ℹ️",
+	"check":        "✅",
+	"success":      "✅",
+	"error":        "❌",
+	"danger":       "🚨",
+	"important":    "❗",
+	"caution":      "⚠️",
+	"question":     "❓",
+	"forbidden":    "🚫",
+	"fire":         "🔥",
+	"star":         "⭐",
+	"pin":          "📌",
+	"clock":        "🕐",
+	"gift":         "🎁",
+	"eyes":         "👀",
+	"bulb":         "💡",
+	"memo":         "📝",
+	"link":         "🔗",
+	"key":          "🔑",
+	"lock":         "🔒",
+	"thumbsup":     "👍",
+	"thumbsdown":   "👎",
+	"rocket":       "🚀",
+	"construction": "🚧",
+}
+
+// calloutEmojiRe matches emoji="<name>" in callout opening tags.
+var calloutEmojiRe = regexp.MustCompile(`(<callout[^>]*\bemoji=")([^"]+)(")`)
+
+// fixCalloutEmoji replaces named emoji aliases in callout tags with actual
+// Unicode emoji characters. fetch-doc sometimes emits emoji="warning" instead
+// of emoji="⚠️"; create-doc only accepts Unicode emoji.
+func fixCalloutEmoji(md string) string {
+	return calloutEmojiRe.ReplaceAllStringFunc(md, func(match string) string {
+		parts := calloutEmojiRe.FindStringSubmatch(match)
+		if len(parts) != 4 {
+			return match
+		}
+		name := parts[2]
+		if emoji, ok := calloutEmojiAliases[name]; ok {
+			return parts[1] + emoji + parts[3]
+		}
+		return match
+	})
+}
+
+// isTableStructuralTag returns true for lark-table tags that are structural
+// (table/tr/td open/close) and should not themselves trigger blank-line insertion.
+func isTableStructuralTag(s string) bool {
+	return strings.HasPrefix(s, "<lark-t") ||
+		strings.HasPrefix(s, "</lark-t")
+}
+
+// contentContainers lists block tags whose interior should have blank lines
+// inserted between adjacent content lines (same treatment as lark-td).
+var contentContainers = [][2]string{
+	{"<lark-td>", "</lark-td>"},
+	{"<callout", "</callout>"},
+	{"<quote-container>", "</quote-container>"},
+}
+
+// listItemRe matches unordered and ordered list item markers, including
+// indented (nested) items.
+var listItemRe = regexp.MustCompile(`^[ \t]*([-*+]|\d+[.)]) `)
+
+// nestedListIndentRe matches nested list item markers indented with pairs of
+// spaces. We rewrite those space pairs to tabs because some downstream
+// round-trip paths treat multi-space indented ordered items as flat items or
+// literal text, while tab indentation remains nested and avoids 4-space code
+// block ambiguity.
+var nestedListIndentRe = regexp.MustCompile(`^( {2,})([-*+]|\d+[.)]) `)
+
+func normalizeNestedListIndentation(md string) string {
+	lines := strings.Split(md, "\n")
+	for i, line := range lines {
+		matches := nestedListIndentRe.FindStringSubmatch(line)
+		if len(matches) != 3 {
+			continue
+		}
+		if !hasPreviousNonBlankListItem(lines, i) {
+			continue
+		}
+		indent := matches[1]
+		if len(indent)%2 != 0 {
+			continue
+		}
+		tabs := strings.Repeat("\t", len(indent)/2)
+		lines[i] = tabs + line[len(indent):]
+	}
+	return strings.Join(lines, "\n")
+}
+
+func hasPreviousNonBlankListItem(lines []string, index int) bool {
+	for i := index - 1; i >= 0; i-- {
+		trimmed := strings.TrimSpace(lines[i])
+		if trimmed == "" {
+			return false
+		}
+		return listItemRe.MatchString(lines[i])
+	}
+	return false
+}
+
+// isListItemOrContinuation returns true for lines that are part of a list:
+// either a list item marker line or an indented continuation of a list item.
+// This is used to prevent blank lines being inserted between tight list lines,
+// which would turn a tight list into a loose list and change rendering.
+func isListItemOrContinuation(line string) bool {
+	if listItemRe.MatchString(line) {
+		return true
+	}
+	// Continuation lines are indented by at least 2 spaces or 1 tab.
+	return strings.HasPrefix(line, "  ") || strings.HasPrefix(line, "\t")
+}
+
+// fixTopLevelSoftbreaks ensures that adjacent non-empty content lines are
+// separated by a blank line in the following contexts:
+//  1. Top level (depth == 0): every Lark block becomes its own Markdown paragraph.
+//  2. Inside content containers (<lark-td>, <callout>, <quote-container>):
+//     multi-line content is preserved as separate paragraphs.
+//
+// Structural table tags (<lark-table>, <lark-tr>, <lark-td> and their closing
+// counterparts) never trigger blank-line insertion themselves. Fenced code
+// blocks (``` ... ```) are left completely untouched. Consecutive list items
+// and list continuations are not separated (to preserve tight lists).
+func fixTopLevelSoftbreaks(md string) string {
+	lines := strings.Split(md, "\n")
+	out := make([]string, 0, len(lines)*2)
+
+	inCodeBlock := false
+	// containerDepth > 0 means we are inside a content container.
+	containerDepth := 0
+	// tableDepth tracks <lark-table> nesting (outer structure, not content).
+	tableDepth := 0
+
+	for i, line := range lines {
+		trimmed := strings.TrimSpace(line)
+
+		// --- Track fenced code blocks — skip all processing inside. ---
+		// Any ``` line opens a block; only plain ``` (no language id) closes it.
+		if strings.HasPrefix(trimmed, "```") {
+			if inCodeBlock {
+				if trimmed == "```" {
+					inCodeBlock = false
+				}
+			} else {
+				inCodeBlock = true
+			}
+			out = append(out, line)
+			continue
+		}
+
+		if !inCodeBlock {
+			// --- Track content containers. ---
+			for _, cc := range contentContainers {
+				if strings.HasPrefix(trimmed, cc[0]) {
+					containerDepth++
+				}
+				if strings.Contains(trimmed, cc[1]) {
+					containerDepth--
+					if containerDepth < 0 {
+						containerDepth = 0
+					}
+				}
+			}
+
+			// --- Track table structure (outer, non-content). ---
+			if strings.HasPrefix(trimmed, "<lark-table") {
+				tableDepth++
+			}
+			if strings.Contains(trimmed, "</lark-table>") {
+				tableDepth--
+				if tableDepth < 0 {
+					tableDepth = 0
+				}
+			}
+		}
+
+		// --- Decide whether to insert a blank line before this line. ---
+		if !inCodeBlock && trimmed != "" && i > 0 {
+			// Skip structural table tags — they are not content lines.
+			isStructural := isTableStructuralTag(trimmed)
+
+			// Don't split consecutive blockquote lines ("> ...") — they form
+			// one continuous blockquote in the original document.
+			isBlockquote := strings.HasPrefix(trimmed, "> ") || trimmed == ">"
+
+			// Only closing container tags suppress blank-line insertion.
+			// Opening container tags may still receive a blank line before them
+			// (e.g. two consecutive <callout> blocks need a blank between them).
+			isContainerTag := false
+			for _, cc := range contentContainers {
+				closingTag := "</" + cc[0][1:]
+				if strings.HasPrefix(trimmed, closingTag) {
+					isContainerTag = true
+					break
+				}
+			}
+
+			// Insert blank line when:
+			//   - at top level (tableDepth == 0, containerDepth == 0), OR
+			//   - inside a content container (containerDepth > 0, not in outer table)
+			// AND this line is actual content (not structural/blockquote/container-tag).
+			inContent := tableDepth == 0 || containerDepth > 0
+			if !isStructural && !isBlockquote && !isContainerTag && inContent {
+				// Don't split consecutive list items / continuations — inserting a
+				// blank line between them turns a tight list into a loose list.
+				isListRelated := isListItemOrContinuation(line)
+				prevIsListRelated := len(out) > 0 && isListItemOrContinuation(out[len(out)-1])
+				if !(isListRelated && prevIsListRelated) {
+					prev := ""
+					if len(out) > 0 {
+						prev = strings.TrimSpace(out[len(out)-1])
+					}
+					if prev != "" && !isTableStructuralTag(prev) {
+						out = append(out, "")
+					}
+				}
+			}
+		}
+
+		out = append(out, line)
+	}
+
+	return strings.Join(out, "\n")
+}

shortcuts/doc/markdown_fix_hardening_test.go

@@ -0,0 +1,287 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestFixExportedMarkdownIdempotent asserts the core promise of the exported
+// markdown pipeline: applying the fixes twice produces the same result as
+// applying them once. Round-trip formatting relies on this invariant, so any
+// transform that keeps rewriting its own output would break fetch → edit →
+// update → fetch stability.
+func TestFixExportedMarkdownIdempotent(t *testing.T) {
+	fixtures := map[string]string{
+		"kitchen sink": strings.Join([]string{
+			"# **Title**",
+			"paragraph one",
+			"paragraph two",
+			"**bold ** and * italic*",
+			"",
+			"> q1",
+			"> q2",
+			"",
+			"1. parent",
+			"  1. child",
+			"    1. grandchild",
+			"",
+			"<callout emoji=\"warning\">",
+			"callout body line 1",
+			"callout body line 2",
+			"</callout>",
+			"",
+			"some text",
+			"---",
+			"",
+			"```go",
+			"// code content with markdown-like shapes must survive as-is",
+			"**foo **",
+			"* hello*",
+			"  1. nested",
+			"> q",
+			"---",
+			"```",
+			"",
+		}, "\n"),
+
+		"cjk content": strings.Join([]string{
+			"# **测试标题**",
+			"段落一",
+			"段落二",
+			"**有用性 ** and * 关键 *",
+			"",
+			"1. 父项",
+			"  1. 子项",
+			"",
+		}, "\n"),
+
+		"nested containers": strings.Join([]string{
+			"<callout emoji=\"info\">",
+			"line a",
+			"line b",
+			"</callout>",
+			"",
+			"<quote-container>",
+			"quoted 1",
+			"quoted 2",
+			"</quote-container>",
+			"",
+		}, "\n"),
+	}
+
+	for name, fixture := range fixtures {
+		t.Run(name, func(t *testing.T) {
+			once := fixExportedMarkdown(fixture)
+			twice := fixExportedMarkdown(once)
+			if once != twice {
+				t.Errorf("fixExportedMarkdown is not idempotent for %q\nfirst pass:\n%s\nsecond pass:\n%s",
+					name, once, twice)
+			}
+		})
+	}
+}
+
+// TestFixExportedMarkdownPreservesFencedCodeByteForByte packs a fenced code
+// block with content that every individual transform in the pipeline would
+// normally rewrite, and asserts the fence content comes out byte-for-byte
+// identical. This is the pipeline's strongest invariant — users' code samples
+// must never be silently modified by a formatting pass.
+func TestFixExportedMarkdownPreservesFencedCodeByteForByte(t *testing.T) {
+	// Every line below is something at least one transform would touch if it
+	// appeared outside a fence. None of it must change.
+	dangerous := strings.Join([]string{
+		"**foo **",      // fixBoldSpacing — trailing space bold
+		"* hello*",      // fixBoldSpacing — leading space italic
+		"# **heading**", // fixBoldSpacing — redundant heading bold
+		"para1",         // fixTopLevelSoftbreaks — adjacent paragraphs
+		"para2",
+		"> q1", // fixBlockquoteHardBreaks — blockquote pair
+		"> q2",
+		"some text", // fixSetextAmbiguity — text before ---
+		"---",
+		"  1. nested",               // normalizeNestedListIndentation
+		`<callout emoji="warning">`, // fixCalloutEmoji — emoji alias
+	}, "\n")
+
+	// Wrap the dangerous content in a triple-backtick fence and surround with
+	// content so the pipeline has adjacent regions to potentially touch.
+	input := "before\n\n```\n" + dangerous + "\n```\n\nafter\n"
+
+	got := fixExportedMarkdown(input)
+
+	// Extract the fence content from the output and compare to the input fence
+	// content byte-for-byte.
+	gotFence, ok := extractFirstFenceContent(got)
+	if !ok {
+		t.Fatalf("fixExportedMarkdown output lost its fenced code block:\n%s", got)
+	}
+	if gotFence != dangerous {
+		t.Errorf("fenced code content was modified\nwant (bytes): %q\ngot  (bytes): %q",
+			dangerous, gotFence)
+	}
+}
+
+// extractFirstFenceContent returns the inner text of the first triple-backtick
+// fenced code block it finds, or ("", false) if none is present.
+func extractFirstFenceContent(md string) (string, bool) {
+	const fence = "```"
+	open := strings.Index(md, fence)
+	if open < 0 {
+		return "", false
+	}
+	// Skip the fence marker and its info-string line.
+	rest := md[open+len(fence):]
+	lineEnd := strings.Index(rest, "\n")
+	if lineEnd < 0 {
+		return "", false
+	}
+	rest = rest[lineEnd+1:]
+	close := strings.Index(rest, "\n"+fence)
+	if close < 0 {
+		return "", false
+	}
+	return rest[:close], true
+}
+
+// TestFixExportedMarkdownPreservesCRLF feeds CRLF-terminated markdown (Windows
+// line endings) through the pipeline and asserts that line endings are
+// preserved AND the emphasis/heading transforms still apply — neither
+// silently-LF-normalized nor passed through unchanged.
+func TestFixExportedMarkdownPreservesCRLF(t *testing.T) {
+	lf := "# **Title**\nparagraph one\nparagraph two\n**bold **\n"
+	crlf := strings.ReplaceAll(lf, "\n", "\r\n")
+
+	got := fixExportedMarkdown(crlf)
+
+	// Transforms must still fire: heading bold stripped, trailing-space bold trimmed.
+	if strings.Contains(got, "**Title**") {
+		t.Errorf("heading bold not stripped on CRLF input:\n%q", got)
+	}
+	if strings.Contains(got, "**bold **") {
+		t.Errorf("trailing-space bold not fixed on CRLF input:\n%q", got)
+	}
+	// CRLF line endings must survive — we don't want to silently normalize a
+	// Windows author's document to LF.
+	if !strings.Contains(got, "\r\n") {
+		t.Errorf("CRLF line endings were normalized away:\n%q", got)
+	}
+}
+
+// TestFixExportedMarkdownTransformInteractions covers shapes where more than
+// one transform fires on the same input. Each transform is individually tested
+// elsewhere; these cases guard against composition regressions.
+func TestFixExportedMarkdownTransformInteractions(t *testing.T) {
+	tests := []struct {
+		name         string
+		input        string
+		wantContains []string // substrings that must be present after fixes
+		wantAbsent   []string // substrings that must be absent after fixes
+	}{
+		{
+			name:  "nested list item with trailing-space bold",
+			input: "1. parent\n  1. **child **\n",
+			wantContains: []string{
+				"\t1.",      // nested indent converted to tab
+				"**child**", // trailing space trimmed
+			},
+			wantAbsent: []string{
+				"  1.",       // original two-space indent gone
+				"**child **", // original trailing space gone
+			},
+		},
+		{
+			name:  "paragraph followed by list",
+			input: "paragraph\n- item a\n- item b\n",
+			wantContains: []string{
+				"paragraph\n\n- item a", // blank line inserted at text-to-list transition
+			},
+			wantAbsent: []string{
+				"\n\n\n", // no triple newline
+			},
+		},
+		{
+			name:  "callout containing list with emphasis",
+			input: "<callout emoji=\"info\">\n- **item **\n- another\n</callout>\n",
+			wantContains: []string{
+				"**item**", // trailing-space bold fixed inside callout
+			},
+			wantAbsent: []string{
+				"**item **",
+			},
+		},
+		{
+			name:  "heading followed by paragraph with bold",
+			input: "# **Title**\nbody **text **\n",
+			wantContains: []string{
+				"# Title",       // heading bold stripped
+				"body **text**", // paragraph bold trimmed, not stripped
+			},
+			wantAbsent: []string{
+				"# **Title**",
+				"body **text **",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := fixExportedMarkdown(tt.input)
+			for _, want := range tt.wantContains {
+				if !strings.Contains(got, want) {
+					t.Errorf("want substring %q not found in output:\n%s", want, got)
+				}
+			}
+			for _, unwanted := range tt.wantAbsent {
+				if strings.Contains(got, unwanted) {
+					t.Errorf("unwanted substring %q still present in output:\n%s", unwanted, got)
+				}
+			}
+		})
+	}
+}
+
+// TestNormalizeNestedListIndentationDocumentedSkips locks in the deliberate
+// "do nothing" branches of normalizeNestedListIndentation. Each case below is
+// a shape the function intentionally does not rewrite; if a future change to
+// the heuristic flips one of these, we want the regression to be visible in
+// the test diff rather than silently changing user documents.
+func TestNormalizeNestedListIndentationDocumentedSkips(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		// want is identical to input — we are asserting "no change".
+	}{
+		{
+			name:  "three-space indent (odd) under list item stays unchanged",
+			input: "1. parent\n   1. child",
+		},
+		{
+			name:  "five-space indent (odd) under list item stays unchanged",
+			input: "- parent\n     - deep",
+		},
+		{
+			name:  "two-space indent without a parent list item stays unchanged",
+			input: "plain paragraph\n  - not nested",
+		},
+		{
+			name:  "blank-line-separated loose-list sibling stays unchanged",
+			input: "1. a\n\n  1. b",
+		},
+		{
+			name:  "four-space indented code block under list item stays unchanged",
+			input: "- parent\n\n    1. code sample",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := normalizeNestedListIndentation(tt.input)
+			if got != tt.input {
+				t.Errorf("normalizeNestedListIndentation unexpectedly rewrote documented-skip input\ninput: %q\ngot:   %q", tt.input, got)
+			}
+		})
+	}
+}

shortcuts/doc/markdown_fix_test.go

@@ -0,0 +1,569 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestFixBoldSpacing(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "leading space after opening bold",
+			input: "** hello**",
+			want:  "**hello**",
+		},
+		{
+			name:  "leading space after opening italic",
+			input: "* hello*",
+			want:  "*hello*",
+		},
+		{
+			name:  "leading and trailing spaces inside bold are collapsed",
+			input: "** hello **",
+			want:  "**hello**",
+		},
+		{
+			name:  "leading and trailing spaces inside italic are collapsed",
+			input: "* hello *",
+			want:  "*hello*",
+		},
+		{
+			name:  "multiple spaced italic spans on one line are each collapsed",
+			input: "* a* * b*",
+			want:  "*a* *b*",
+		},
+		{
+			name:  "ambiguous italic span stays literal",
+			input: "2 * x * y",
+			want:  "2 * x * y",
+		},
+		{
+			name:  "ambiguous bold span stays literal",
+			input: "2 ** x ** y",
+			want:  "2 ** x ** y",
+		},
+		{
+			name:  "single-rune italic with spaces on both sides stays literal",
+			input: "* x *",
+			want:  "* x *",
+		},
+		{
+			name:  "single-rune bold with spaces on both sides stays literal",
+			input: "** x **",
+			want:  "** x **",
+		},
+		{
+			name:  "triple-asterisk near miss stays literal",
+			input: "*** hello**",
+			want:  "*** hello**",
+		},
+		{
+			name:  "trailing space before closing bold",
+			input: "**hello **",
+			want:  "**hello**",
+		},
+		{
+			name:  "trailing space before closing italic",
+			input: "*hello *",
+			want:  "*hello*",
+		},
+		{
+			name:  "redundant bold in h1",
+			input: "# **Title**",
+			want:  "# Title",
+		},
+		{
+			name:  "redundant bold in h2",
+			input: "## **Section**",
+			want:  "## Section",
+		},
+		{
+			name:  "no change needed for clean bold",
+			input: "**bold**",
+			want:  "**bold**",
+		},
+		{
+			name:  "multiple lines processed independently",
+			input: "**foo **\n**bar **",
+			want:  "**foo**\n**bar**",
+		},
+		{
+			name:  "inline code span not modified",
+			input: "`**hello **`",
+			want:  "`**hello **`",
+		},
+		{
+			name:  "inline code preserved, bold outside fixed",
+			input: "**foo ** and `**bar **`",
+			want:  "**foo** and `**bar **`",
+		},
+		{
+			name:  "inline code with spaced italic stays literal while outside span is fixed",
+			input: "`* hello *` and * hello *",
+			want:  "`* hello *` and *hello*",
+		},
+		{
+			name:  "opening space inside text tag fixed",
+			input: `<text color="red">** Helpful - 有用性：**</text>`,
+			want:  `<text color="red">**Helpful - 有用性：**</text>`,
+		},
+		{
+			name:  "double-backtick inline code not modified",
+			input: "``**hello **`` and **world **",
+			want:  "``**hello **`` and **world**",
+		},
+		{
+			name:  "double-backtick span containing literal backtick not modified",
+			input: "`` a`b `` and **bold **",
+			want:  "`` a`b `` and **bold**",
+		},
+		{
+			name:  "heading with multiple bold spans left unchanged",
+			input: "# **foo** and **bar**",
+			want:  "# **foo** and **bar**",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := fixBoldSpacing(tt.input)
+			if got != tt.want {
+				t.Errorf("fixBoldSpacing(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFixSetextAmbiguity(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "paragraph followed by ---",
+			input: "some text\n---",
+			want:  "some text\n\n---",
+		},
+		{
+			name:  "blank line before --- already",
+			input: "some text\n\n---",
+			want:  "some text\n\n---",
+		},
+		{
+			name:  "heading not affected",
+			input: "# Heading\n---",
+			want:  "# Heading\n\n---",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := fixSetextAmbiguity(tt.input)
+			if got != tt.want {
+				t.Errorf("fixSetextAmbiguity(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFixBlockquoteHardBreaks(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "two consecutive blockquote lines",
+			input: "> line1\n> line2",
+			want:  "> line1\n>\n> line2",
+		},
+		{
+			name:  "three consecutive blockquote lines",
+			input: "> a\n> b\n> c",
+			want:  "> a\n>\n> b\n>\n> c",
+		},
+		{
+			name:  "single blockquote line unchanged",
+			input: "> only one",
+			want:  "> only one",
+		},
+		{
+			name:  "non-blockquote not affected",
+			input: "line1\nline2",
+			want:  "line1\nline2",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := fixBlockquoteHardBreaks(tt.input)
+			if got != tt.want {
+				t.Errorf("fixBlockquoteHardBreaks(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFixTopLevelSoftbreaks(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "adjacent top-level lines get blank line",
+			input: "paragraph one\nparagraph two",
+			want:  "paragraph one\n\nparagraph two",
+		},
+		{
+			name:  "lines inside code block not modified",
+			input: "```\nline1\nline2\n```",
+			want:  "```\nline1\nline2\n```",
+		},
+		{
+			// callout is a content container: blank lines are inserted between inner lines.
+			name:  "lines inside callout get blank line between them",
+			input: "<callout>\nline1\nline2\n</callout>",
+			want:  "<callout>\n\nline1\n\nline2\n</callout>",
+		},
+		{
+			name:  "lark-td cell content gets blank line",
+			input: "<lark-td>\nline1\nline2\n</lark-td>",
+			want:  "<lark-td>\nline1\n\nline2\n</lark-td>",
+		},
+		{
+			name:  "structural lark-table tags not separated",
+			input: "<lark-table>\n<lark-tr>\n<lark-td>\ncontent\n</lark-td>\n</lark-tr>\n</lark-table>",
+			want:  "<lark-table>\n<lark-tr>\n<lark-td>\ncontent\n</lark-td>\n</lark-tr>\n</lark-table>",
+		},
+		{
+			name:  "blockquote lines not split",
+			input: "> line1\n> line2",
+			want:  "> line1\n> line2",
+		},
+		{
+			name:  "consecutive unordered list items not split",
+			input: "- item a\n- item b\n- item c",
+			want:  "- item a\n- item b\n- item c",
+		},
+		{
+			name:  "consecutive ordered list items not split",
+			input: "1. first\n2. second\n3. third",
+			want:  "1. first\n2. second\n3. third",
+		},
+		{
+			name:  "list continuation not split from item",
+			input: "- item a\n  continuation",
+			want:  "- item a\n  continuation",
+		},
+		{
+			name:  "text to list transition gets blank line",
+			input: "paragraph\n- list item",
+			want:  "paragraph\n\n- list item",
+		},
+		{
+			name:  "adjacent callout blocks get blank line between them",
+			input: "<callout>\ncontent1\n</callout>\n<callout>\ncontent2\n</callout>",
+			want:  "<callout>\n\ncontent1\n</callout>\n\n<callout>\n\ncontent2\n</callout>",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := fixTopLevelSoftbreaks(tt.input)
+			if got != tt.want {
+				t.Errorf("fixTopLevelSoftbreaks(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestNormalizeNestedListIndentation(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "nested ordered list uses tabs instead of space pairs",
+			input: "1. parent\n  1. child\n    1. grandchild",
+			want:  "1. parent\n\t1. child\n\t\t1. grandchild",
+		},
+		{
+			name:  "nested mixed list markers use tabs instead of space pairs",
+			input: "- parent\n  - child\n    1. grandchild",
+			want:  "- parent\n\t- child\n\t\t1. grandchild",
+		},
+		{
+			name:  "top-level list unchanged",
+			input: "1. parent\n2. sibling",
+			want:  "1. parent\n2. sibling",
+		},
+		{
+			name:  "indented top-level marker without parent list stays unchanged",
+			input: "paragraph\n\n  1. item",
+			want:  "paragraph\n\n  1. item",
+		},
+		{
+			name:  "blank-line-separated loose-list sibling stays unchanged",
+			input: "1. a\n\n  1. b",
+			want:  "1. a\n\n  1. b",
+		},
+		{
+			name:  "indented code block inside list item stays unchanged",
+			input: "- parent\n\n    1. code",
+			want:  "- parent\n\n    1. code",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := normalizeNestedListIndentation(tt.input)
+			if got != tt.want {
+				t.Errorf("normalizeNestedListIndentation(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFixExportedMarkdown(t *testing.T) {
+	// End-to-end: all fixes applied together
+	input := "# **Title**\nparagraph one\nparagraph two\n**bold **\n> q1\n> q2\nsome text\n---"
+	result := fixExportedMarkdown(input)
+
+	if strings.Contains(result, "# **Title**") {
+		t.Error("expected heading bold to be stripped")
+	}
+	if !strings.Contains(result, "paragraph one\n\nparagraph two") {
+		t.Error("expected blank line between top-level paragraphs")
+	}
+	if strings.Contains(result, "**bold **") {
+		t.Error("expected trailing space in bold to be fixed")
+	}
+	if !strings.Contains(result, ">\n> q2") {
+		t.Error("expected blockquote hard break inserted")
+	}
+	if strings.Contains(result, "some text\n---") {
+		t.Error("expected blank line before --- to prevent setext heading")
+	}
+	// Should end with exactly one newline
+	if !strings.HasSuffix(result, "\n") || strings.HasSuffix(result, "\n\n") {
+		t.Errorf("expected result to end with exactly one newline, got %q", result[len(result)-5:])
+	}
+	// No triple newlines
+	if strings.Contains(result, "\n\n\n") {
+		t.Error("expected no triple newlines in output")
+	}
+}
+
+func TestWarnCalloutType(t *testing.T) {
+	tests := []struct {
+		name         string
+		input        string
+		wantHint     bool   // whether a hint line is expected
+		hintContains string // substring the hint must contain
+	}{
+		{
+			name:         "warning type without background-color emits hint",
+			input:        `<callout type="warning" emoji="📝">`,
+			wantHint:     true,
+			hintContains: `background-color="light-yellow"`,
+		},
+		{
+			name:         "info type without background-color emits hint",
+			input:        `<callout type="info" emoji="ℹ️">`,
+			wantHint:     true,
+			hintContains: `background-color="light-blue"`,
+		},
+		{
+			name:         "single-quoted type attribute emits hint",
+			input:        `<callout type='warning' emoji="📝">`,
+			wantHint:     true,
+			hintContains: `background-color="light-yellow"`,
+		},
+		{
+			name:     "explicit background-color suppresses hint",
+			input:    `<callout type="warning" emoji="📝" background-color="light-red">`,
+			wantHint: false,
+		},
+		{
+			name:     "whitespace around equals is tolerated in background-color",
+			input:    `<callout type="warning" emoji="📝" background-color = "light-red">`,
+			wantHint: false,
+		},
+		{
+			name:     "unknown type emits no hint",
+			input:    `<callout type="custom" emoji="🔥">`,
+			wantHint: false,
+		},
+		{
+			name:     "no type attribute emits no hint",
+			input:    `<callout emoji="💡" background-color="light-green">`,
+			wantHint: false,
+		},
+		{
+			name:     "non-callout tag emits no hint",
+			input:    `<div type="warning">`,
+			wantHint: false,
+		},
+		{
+			name:         "hint includes border-color suggestion",
+			input:        `<callout type="error" emoji="❌">`,
+			wantHint:     true,
+			hintContains: `border-color="red"`,
+		},
+		{
+			// Regression: the old `\btype=` regex matched the suffix of
+			// `data-type=` because `-` is a non-word character, so a tag
+			// carrying only data-attrs would silently get a bogus hint.
+			// The (?:^|\s) anchor requires a real attribute separator.
+			name:     "data-type attribute does not trigger hint",
+			input:    `<callout data-type="warning" emoji="📝">`,
+			wantHint: false,
+		},
+		{
+			// Symmetric guard for the background-color regex: a future
+			// `data-background-color=` attribute must not be mistaken
+			// for a present background-color and silently suppress the
+			// hint that the real type= would otherwise produce.
+			name:         "data-background-color does not suppress hint",
+			input:        `<callout type="warning" data-background-color="anything">`,
+			wantHint:     true,
+			hintContains: `background-color="light-yellow"`,
+		},
+		{
+			// Regression for the code-fence skip: a documentation sample
+			// inside a ``` fence is NOT a real callout the user wants
+			// rendered, so it must produce no stderr noise.
+			name: "callout inside backtick fence emits no hint",
+			input: "```markdown\n" +
+				`<callout type="warning" emoji="📝">` + "\n" +
+				"```\n",
+			wantHint: false,
+		},
+		{
+			// Same skip works for tilde fences (CommonMark §4.5 makes
+			// `~~~` an equivalent fence character).
+			name: "callout inside tilde fence emits no hint",
+			input: "~~~markdown\n" +
+				`<callout type="info" emoji="ℹ️">` + "\n" +
+				"~~~\n",
+			wantHint: false,
+		},
+		{
+			// Closing the fence must restore normal scanning: a real
+			// callout that follows a documentation block still gets a
+			// hint. Pins that fenceMarker is reset, not stuck.
+			name: "callout after fence close still emits hint",
+			input: "```markdown\n" +
+				`<callout type="warning">sample</callout>` + "\n" +
+				"```\n" +
+				`<callout type="error" emoji="❌">real</callout>` + "\n",
+			wantHint:     true,
+			hintContains: `border-color="red"`,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var buf strings.Builder
+			WarnCalloutType(tt.input, &buf)
+			got := buf.String()
+			if tt.wantHint {
+				if got == "" {
+					t.Errorf("WarnCalloutType(%q): expected hint, got no output", tt.input)
+					return
+				}
+				if tt.hintContains != "" && !strings.Contains(got, tt.hintContains) {
+					t.Errorf("WarnCalloutType(%q): hint %q missing %q", tt.input, got, tt.hintContains)
+				}
+			} else {
+				if got != "" {
+					t.Errorf("WarnCalloutType(%q): expected no output, got %q", tt.input, got)
+				}
+			}
+		})
+	}
+}
+
+func TestFixCalloutEmoji(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "warning alias replaced",
+			input: `<callout emoji="warning" background-color="light-orange">`,
+			want:  `<callout emoji="⚠️" background-color="light-orange">`,
+		},
+		{
+			name:  "tip alias replaced",
+			input: `<callout emoji="tip">`,
+			want:  `<callout emoji="💡">`,
+		},
+		{
+			name:  "actual emoji unchanged",
+			input: `<callout emoji="⚠️">`,
+			want:  `<callout emoji="⚠️">`,
+		},
+		{
+			name:  "unknown alias unchanged",
+			input: `<callout emoji="unicorn">`,
+			want:  `<callout emoji="unicorn">`,
+		},
+		{
+			name:  "non-callout tag unchanged",
+			input: `<div emoji="warning">`,
+			want:  `<div emoji="warning">`,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := fixCalloutEmoji(tt.input)
+			if got != tt.want {
+				t.Errorf("fixCalloutEmoji(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestApplyOutsideCodeFences(t *testing.T) {
+	// Transforms should not modify content inside fenced code blocks.
+	input := "```md\n**x **\n> a\n> b\nline\n---\n```"
+
+	if got := applyOutsideCodeFences(input, fixBoldSpacing); got != input {
+		t.Fatalf("fixBoldSpacing (via applyOutsideCodeFences) modified fenced code:\ngot  %q\nwant %q", got, input)
+	}
+	if got := applyOutsideCodeFences(input, fixSetextAmbiguity); got != input {
+		t.Fatalf("fixSetextAmbiguity (via applyOutsideCodeFences) modified fenced code:\ngot  %q\nwant %q", got, input)
+	}
+	if got := applyOutsideCodeFences(input, fixBlockquoteHardBreaks); got != input {
+		t.Fatalf("fixBlockquoteHardBreaks (via applyOutsideCodeFences) modified fenced code:\ngot  %q\nwant %q", got, input)
+	}
+
+	// Content outside the fence should still be transformed.
+	mixed := "**foo ** before\n```\n**x **\n```\n**bar ** after"
+	got := applyOutsideCodeFences(mixed, fixBoldSpacing)
+	if strings.Contains(got, "**foo **") {
+		t.Errorf("fixBoldSpacing did not fix bold before fence: %q", got)
+	}
+	if strings.Contains(got, "**bar **") {
+		t.Errorf("fixBoldSpacing did not fix bold after fence: %q", got)
+	}
+	if !strings.Contains(got, "```\n**x **\n```") {
+		t.Errorf("fixBoldSpacing modified content inside fence: %q", got)
+	}
+}
+
+func TestFixTopLevelSoftbreaksQuoteContainer(t *testing.T) {
+	input := "<quote-container>\nline1\nline2\n</quote-container>"
+	got := fixTopLevelSoftbreaks(input)
+	// quote-container is a content container: blank lines inserted between inner lines.
+	want := "<quote-container>\n\nline1\n\nline2\n</quote-container>"
+	if got != want {
+		t.Errorf("fixTopLevelSoftbreaks quote-container = %q, want %q", got, want)
+	}
+}

shortcuts/doc/shortcuts.go

@@ -9,44 +9,28 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
 const docsServiceHelpDefault = `Document and content operations.`
 
-const docsSkillReadCommand = "lark-cli skills read lark-doc"
-const docsXMLSkillReadCommand = "lark-cli skills read lark-doc references/lark-doc-xml.md"
-const docsMDSkillReadCommand = "lark-cli skills read lark-doc references/lark-doc-md.md"
-const docsContentSkillHelp = "AI agents MUST read " +
-	docsXMLSkillReadCommand + " before writing any --content payload; " +
-	"when using --doc-format markdown, also read " + docsMDSkillReadCommand + ". " +
-	"Follow the latest rules there, and MUST NOT grep/open local SKILL.md files " +
-	"to discover this guidance"
+const docsServiceHelpV2 = `Document and content operations (v2).`
 
-func docsSkillReadCommandForShortcut(shortcut string) string {
-	switch strings.TrimPrefix(shortcut, "+") {
-	case "create":
-		return docsSkillReadCommand + " references/lark-doc-create.md"
-	case "fetch":
-		return docsSkillReadCommand + " references/lark-doc-fetch.md"
-	case "update":
-		return docsSkillReadCommand + " references/lark-doc-update.md"
-	default:
-		return docsSkillReadCommand
-	}
+var docsVersionSelectionTips = []string{
+	"Docs v1 is deprecated and will be removed soon. Check the installed lark-doc skill first; if it is not the v2 skill, run `lark-cli update` to upgrade skills.",
+	"After confirming lark-doc is v2, follow that skill's examples and use `--api-version v2` with docs +create, docs +fetch, and docs +update.",
 }
 
-func docsHelpCommandForShortcut(shortcut string) string {
-	switch strings.TrimPrefix(shortcut, "+") {
-	case "create":
-		return "lark-cli docs +create --help"
-	case "fetch":
-		return "lark-cli docs +fetch --help"
-	case "update":
-		return "lark-cli docs +update --help"
-	default:
-		return "lark-cli docs --help"
+var docsV2VersionSelectionTips = []string{
+	"Check the installed lark-doc skill first; if it is not the v2 skill, run `lark-cli update` to upgrade skills.",
+}
+
+func docsTipsForVersion(apiVersion string) []string {
+	if apiVersion == "v2" {
+		return docsV2VersionSelectionTips
 	}
+	return docsVersionSelectionTips
 }
 
 // Shortcuts returns all docs shortcuts.
@@ -64,32 +48,45 @@ func Shortcuts() []common.Shortcut {
 }
 
 // ConfigureServiceHelp adds docs-specific guidance to the parent `docs` command.
+// The shortcut-level help remains compatible with legacy v1 skills; this parent
+// help switches docs guidance to match the selected API version.
 func ConfigureServiceHelp(cmd *cobra.Command) {
 	if cmd == nil {
 		return
 	}
-	cmd.Long = docsHelpLong(docsServiceHelpDefault, docsSkillReadCommand)
-}
-
-func installDocsShortcutHelp(command string) func(*cobra.Command) {
-	return func(cmd *cobra.Command) {
-		cmd.Long = docsHelpLong(cmd.Short, docsSkillReadCommandForShortcut(command))
+	serviceCmd := cmd
+	cmd.Long = strings.TrimSpace(docsServiceHelpDefault)
+	if cmd.Flags().Lookup("api-version") == nil {
+		cmd.Flags().String("api-version", "", "show docs help for API version (v1|v2)")
+		cmdutil.RegisterFlagCompletion(cmd, "api-version", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+			return []string{"v1", "v2"}, cobra.ShellCompDirectiveNoFileComp
+		})
 	}
-}
-
-func docsHelpLong(summary, skillReadCommand string) string {
-	return strings.TrimSpace(fmt.Sprintf(`%s
-
-Start here (required for AI agents):
-  %s
-
-  AI agents MUST read the matching embedded skill before choosing flags
-  or running docs commands. Do not skip this step, and do not infer
-  workflows from --help alone. MUST NOT grep/open local SKILL.md files
-  to discover this guidance; use %s so content stays version-matched
-  with this CLI. Skills ship with the CLI and include docs workflows,
-  selector/block-id usage, XML/Markdown formats, and copy-paste examples.
-
-  skills read lark-doc                Docs workflow guide
-  skills read lark-doc <path>         Read a referenced docs skill file`, strings.TrimSpace(summary), skillReadCommand, skillReadCommand))
+
+	defaultHelp := cmd.HelpFunc()
+	cmd.SetHelpFunc(func(cmd *cobra.Command, args []string) {
+		if cmd != serviceCmd {
+			defaultHelp(cmd, args)
+			return
+		}
+
+		apiVersion, _ := cmd.Flags().GetString("api-version")
+		previousLong := cmd.Long
+		if apiVersion == "v2" {
+			cmd.Long = strings.TrimSpace(docsServiceHelpV2)
+		} else {
+			cmd.Long = strings.TrimSpace(docsServiceHelpDefault)
+		}
+		defer func() {
+			cmd.Long = previousLong
+		}()
+
+		defaultHelp(cmd, args)
+		out := cmd.OutOrStdout()
+		fmt.Fprintln(out)
+		fmt.Fprintln(out, "Tips:")
+		for _, tip := range docsTipsForVersion(apiVersion) {
+			fmt.Fprintf(out, "    • %s\n", tip)
+		}
+	})
 }

shortcuts/doc/v2_only.go

@@ -1,103 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"strings"
-
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-type docsLegacyFlag struct {
-	Name        string
-	Replacement string
-}
-
-func docsAPIVersionCompatFlag() common.Flag {
-	return common.Flag{
-		Name:    "api-version",
-		Desc:    "deprecated compatibility flag; docs shortcuts always use v2, and both v1/v2 are accepted for rollback-safe skill examples",
-		Default: "v2",
-	}
-}
-
-func docsCreateLegacyFlags() []docsLegacyFlag {
-	return []docsLegacyFlag{
-		{Name: "title", Replacement: "put the title in --content, for example <title>Title</title>"},
-		{Name: "markdown", Replacement: "use --content with --doc-format markdown"},
-		{Name: "folder-token", Replacement: "use --parent-token"},
-		{Name: "wiki-node", Replacement: "use --parent-token"},
-		{Name: "wiki-space", Replacement: "use --parent-position my_library or a concrete parent position"},
-	}
-}
-
-func docsFetchLegacyFlags() []docsLegacyFlag {
-	return []docsLegacyFlag{
-		{Name: "offset", Replacement: "use --scope outline/range/keyword/section for partial reads"},
-		{Name: "limit", Replacement: "use --scope outline/range/keyword/section for partial reads"},
-	}
-}
-
-func docsUpdateLegacyFlags() []docsLegacyFlag {
-	return []docsLegacyFlag{
-		{Name: "mode", Replacement: "use --command"},
-		{Name: "markdown", Replacement: "use --content with --doc-format markdown"},
-		{Name: "selection-with-ellipsis", Replacement: "use --command str_replace with --pattern"},
-		{Name: "selection-by-title", Replacement: "fetch block ids first, then use --command block_replace/block_insert_after with --block-id"},
-		{Name: "new-title", Replacement: "update the title through XML content in --content"},
-	}
-}
-
-func docsLegacyFlagDefinitions(flags []docsLegacyFlag) []common.Flag {
-	out := make([]common.Flag, 0, len(flags))
-	for _, flag := range flags {
-		out = append(out, common.Flag{
-			Name:   flag.Name,
-			Desc:   "deprecated v1 compatibility flag; run `lark-cli skills read lark-doc` for the v2 CLI skill",
-			Hidden: true,
-		})
-	}
-	return out
-}
-
-func validateDocsV2Only(runtime *common.RuntimeContext, shortcut string, legacyFlags []docsLegacyFlag) error {
-	switch apiVersion := strings.TrimSpace(runtime.Str("api-version")); apiVersion {
-	case "", "v1", "v2":
-	default:
-		return docsV2OnlyError(shortcut, "--api-version is deprecated and only accepts v1 or v2; both values execute the v2 API")
-	}
-
-	var used []string
-	var replacements []string
-	for _, flag := range legacyFlags {
-		if !runtime.Changed(flag.Name) {
-			continue
-		}
-		used = append(used, "--"+flag.Name)
-		if flag.Replacement != "" {
-			replacements = append(replacements, "--"+flag.Name+" -> "+flag.Replacement)
-		}
-	}
-	if len(used) == 0 {
-		return nil
-	}
-
-	detail := "the old v1 interface has been shut down; legacy v1 flag(s) " + strings.Join(used, ", ") + " are no longer supported"
-	if len(replacements) > 0 {
-		detail += "; " + strings.Join(replacements, "; ")
-	}
-	return docsV2OnlyError(shortcut, detail)
-}
-
-func docsV2OnlyError(shortcut, detail string) error {
-	return common.FlagErrorf(
-		"docs %s is v2-only; %s. Run `%s` for the current schema and examples. AI agents MUST read `%s` (XML) or `%s` (Markdown) and follow the latest format rules there. MUST NOT grep/open local SKILL.md files to discover this guidance; use `lark-cli skills read ...` so content stays version-matched with this CLI. Run `%s` for the latest command flags",
-		shortcut,
-		detail,
-		docsSkillReadCommandForShortcut(shortcut),
-		docsXMLSkillReadCommand,
-		docsMDSkillReadCommand,
-		docsHelpCommandForShortcut(shortcut),
-	)
-}

shortcuts/doc/v2_only_test.go

@@ -1,86 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/shortcuts/common"
-	"github.com/spf13/cobra"
-)
-
-func TestValidateDocsV2OnlyAllowsDefaultAndDeprecatedAPIVersionValues(t *testing.T) {
-	for _, apiVersion := range []string{"", "v1", "v2"} {
-		t.Run(apiVersion, func(t *testing.T) {
-			runtime := docsV2OnlyTestRuntime(t, apiVersion, false)
-			if err := validateDocsV2Only(runtime, "+update", []docsLegacyFlag{{Name: "mode", Replacement: "use --command"}}); err != nil {
-				t.Fatalf("validateDocsV2Only(%q) error = %v, want nil", apiVersion, err)
-			}
-		})
-	}
-}
-
-func TestValidateDocsV2OnlyRejectsUnknownAPIVersion(t *testing.T) {
-	runtime := docsV2OnlyTestRuntime(t, "v0", false)
-	err := validateDocsV2Only(runtime, "+fetch", nil)
-	if err == nil {
-		t.Fatal("expected unknown --api-version to be rejected")
-	}
-	for _, want := range []string{
-		"docs +fetch is v2-only",
-		"--api-version is deprecated and only accepts v1 or v2",
-		"both values execute the v2 API",
-		"lark-cli skills read lark-doc references/lark-doc-fetch.md",
-		"lark-cli skills read lark-doc references/lark-doc-xml.md",
-		"lark-cli skills read lark-doc references/lark-doc-md.md",
-		"MUST NOT grep/open local SKILL.md files",
-		"lark-cli docs +fetch --help",
-	} {
-		if !strings.Contains(err.Error(), want) {
-			t.Fatalf("error missing %q: %v", want, err)
-		}
-	}
-}
-
-func TestValidateDocsV2OnlyRejectsChangedLegacyFlags(t *testing.T) {
-	runtime := docsV2OnlyTestRuntime(t, "", true)
-	err := validateDocsV2Only(runtime, "+update", []docsLegacyFlag{{Name: "mode", Replacement: "use --command"}})
-	if err == nil {
-		t.Fatal("expected changed legacy flag to be rejected")
-	}
-	for _, want := range []string{
-		"the old v1 interface has been shut down",
-		"legacy v1 flag(s) --mode are no longer supported",
-		"--mode -> use --command",
-		"lark-cli skills read lark-doc references/lark-doc-update.md",
-		"lark-cli skills read lark-doc references/lark-doc-xml.md",
-		"lark-cli skills read lark-doc references/lark-doc-md.md",
-		"MUST NOT grep/open local SKILL.md files",
-		"lark-cli docs +update --help",
-	} {
-		if !strings.Contains(err.Error(), want) {
-			t.Fatalf("error missing %q: %v", want, err)
-		}
-	}
-}
-
-func docsV2OnlyTestRuntime(t *testing.T, apiVersion string, legacyMode bool) *common.RuntimeContext {
-	t.Helper()
-
-	cmd := &cobra.Command{Use: "+update"}
-	cmd.Flags().String("api-version", "", "")
-	cmd.Flags().String("mode", "", "")
-	if apiVersion != "" {
-		if err := cmd.Flags().Set("api-version", apiVersion); err != nil {
-			t.Fatalf("set api-version: %v", err)
-		}
-	}
-	if legacyMode {
-		if err := cmd.Flags().Set("mode", "overwrite"); err != nil {
-			t.Fatalf("set mode: %v", err)
-		}
-	}
-	return common.TestNewRuntimeContext(cmd, nil)
-}

shortcuts/doc/versioned_help.go

@@ -0,0 +1,44 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"fmt"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// installVersionedHelp sets a custom help function on cmd that shows only the
+// flags relevant to the selected --api-version. flagVersions maps flag name to
+// its version ("v1" or "v2"). Flags not in the map are treated as shared and
+// always visible.
+func installVersionedHelp(cmd *cobra.Command, defaultVersion string, flagVersions map[string]string) {
+	origHelp := cmd.HelpFunc()
+	cmd.SetHelpFunc(func(cmd *cobra.Command, args []string) {
+		ver, _ := cmd.Flags().GetString("api-version")
+		if ver == "" {
+			ver = defaultVersion
+		}
+		// Show/hide flags based on the active version.
+		cmd.Flags().VisitAll(func(f *pflag.Flag) {
+			if fv, ok := flagVersions[f.Name]; ok {
+				f.Hidden = fv != ver
+			}
+		})
+		cmdutil.SetTips(cmd, docsTipsForVersion(ver))
+		origHelp(cmd, args)
+	})
+}
+
+// warnDeprecatedV1 prints a deprecation notice to stderr when the v1 (MCP) code
+// path is used.
+func warnDeprecatedV1(runtime *common.RuntimeContext, shortcut string) {
+	fmt.Fprintf(runtime.IO().ErrOut,
+		"[deprecated] docs %s is using the v1 API. %s\n",
+		shortcut, docsV2VersionSelectionTips[0])
+}

shortcuts/doc/versioned_help_test.go

@@ -0,0 +1,36 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestWarnDeprecatedV1SuggestsSkillUpdate(t *testing.T) {
+	for _, shortcut := range []string{"+create", "+fetch", "+update"} {
+		t.Run(shortcut, func(t *testing.T) {
+			f, _, stderr, _ := cmdutil.TestFactory(t, &core.CliConfig{})
+			warnDeprecatedV1(&common.RuntimeContext{Factory: f}, shortcut)
+
+			got := stderr.String()
+			for _, want := range []string{
+				"[deprecated] docs " + shortcut + " is using the v1 API.",
+				"Check the installed lark-doc skill first",
+				"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
+			} {
+				if !strings.Contains(got, want) {
+					t.Fatalf("warning missing %q:\n%s", want, got)
+				}
+			}
+			if strings.Contains(got, "will be removed in a future release") {
+				t.Fatalf("warning should not include removal-only guidance:\n%s", got)
+			}
+		})
+	}
+}

shortcuts/drive/drive_inspect.go

@@ -8,19 +8,11 @@ import (
 	"fmt"
 	"io"
 	"strings"
-	"time"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-const (
-	driveInspectRateLimitRetries    = 2
-	driveInspectRetryInitialBackoff = 200 * time.Millisecond
-)
-
-var driveInspectAfter = time.After
-
 var DriveInspect = common.Shortcut{
 	Service:           "drive",
 	Command:           "+inspect",
@@ -43,15 +35,32 @@ var DriveInspect = common.Shortcut{
 		},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if _, err := driveInspectResolveRef(runtime); err != nil {
-			return err
+		raw := strings.TrimSpace(runtime.Str("url"))
+		if raw == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--url cannot be empty").WithParam("--url")
+		}
+
+		_, ok := common.ParseResourceURL(raw)
+		if !ok {
+			// Not a recognized URL pattern.
+			if strings.Contains(raw, "://") {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --url %q: use a recognized Lark document URL or a bare token with --type", raw).WithParam("--url")
+			}
+			// Bare token: --type is required.
+			if strings.TrimSpace(runtime.Str("type")) == "" {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--type is required when --url is a bare token (allowed: doc, docx, sheet, bitable, wiki, file, folder, mindnote, slides)").WithParam("--type")
+			}
 		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		ref, err := driveInspectResolveRef(runtime)
-		if err != nil {
-			return common.NewDryRunAPI()
+		raw := strings.TrimSpace(runtime.Str("url"))
+		ref, ok := common.ParseResourceURL(raw)
+		if !ok {
+			ref = common.ResourceRef{
+				Type:  strings.TrimSpace(runtime.Str("type")),
+				Token: raw,
+			}
 		}
 
 		dry := common.NewDryRunAPI()
@@ -82,9 +91,15 @@ var DriveInspect = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		raw := strings.TrimSpace(runtime.Str("url"))
-		ref, err := driveInspectResolveRef(runtime)
-		if err != nil {
-			return err
+
+		// Step 1: Parse URL to extract {type, token}.
+		ref, ok := common.ParseResourceURL(raw)
+		if !ok {
+			// Bare token: use --type.
+			ref = common.ResourceRef{
+				Type:  strings.TrimSpace(runtime.Str("type")),
+				Token: raw,
+			}
 		}
 
 		inputURL := raw
@@ -96,19 +111,14 @@ var DriveInspect = common.Shortcut{
 		// Step 2: If type is "wiki", unwrap via get_node API.
 		if docType == "wiki" {
 			fmt.Fprintf(runtime.IO().ErrOut, "Inspecting wiki node: %s\n", common.MaskToken(docToken))
-			data, err := driveInspectCallWithRetry(
-				ctx,
-				func() (map[string]interface{}, error) {
-					return runtime.CallAPITyped(
-						"GET",
-						"/open-apis/wiki/v2/spaces/get_node",
-						map[string]interface{}{"token": docToken},
-						nil,
-					)
-				},
+			data, err := runtime.CallAPITyped(
+				"GET",
+				"/open-apis/wiki/v2/spaces/get_node",
+				map[string]interface{}{"token": docToken},
+				nil,
 			)
 			if err != nil {
-				return driveInspectAnnotateError("resolve_wiki", err)
+				return err
 			}
 
 			node := common.GetMap(data, "node")
@@ -135,9 +145,9 @@ var DriveInspect = common.Shortcut{
 		}
 
 		// Step 3: Call batch_query to verify and get title.
-		title, err := driveInspectFetchMetaTitle(ctx, runtime, docToken, docType)
+		title, err := common.FetchDriveMetaTitle(runtime, docToken, docType)
 		if err != nil {
-			return driveInspectAnnotateError("query_meta", err)
+			return err
 		}
 
 		// Step 4: Build the resolved URL.
@@ -171,116 +181,3 @@ var DriveInspect = common.Shortcut{
 		return nil
 	},
 }
-
-func driveInspectResolveRef(runtime *common.RuntimeContext) (common.ResourceRef, error) {
-	raw := strings.TrimSpace(runtime.Str("url"))
-	if raw == "" {
-		return common.ResourceRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--url cannot be empty").WithParam("--url")
-	}
-
-	inputType := strings.ToLower(strings.TrimSpace(runtime.Str("type")))
-	ref, ok := common.ParseResourceURL(raw)
-	if ok {
-		if inputType != "" && inputType != ref.Type {
-			return common.ResourceRef{}, errs.NewValidationError(
-				errs.SubtypeInvalidArgument,
-				"--type %q conflicts with URL path type %q; remove --type or use a matching value",
-				inputType,
-				ref.Type,
-			).WithParam("--type")
-		}
-		return ref, nil
-	}
-
-	if strings.Contains(raw, "://") {
-		return common.ResourceRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "unsupported --url %q: use a recognized Lark document URL or a bare token with --type", raw).WithParam("--url")
-	}
-	if strings.ContainsAny(raw, "/?#") {
-		return common.ResourceRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid bare token %q: remove path/query fragments and pass only the raw token with --type", raw).WithParam("--url")
-	}
-	if inputType == "" {
-		return common.ResourceRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "--type is required when --url is a bare token (allowed: doc, docx, sheet, bitable, wiki, file, folder, mindnote, slides)").WithParam("--type")
-	}
-	return common.ResourceRef{Type: inputType, Token: raw}, nil
-}
-
-func driveInspectFetchMetaTitle(ctx context.Context, runtime *common.RuntimeContext, token, docType string) (string, error) {
-	var title string
-	_, err := driveInspectCallWithRetry(ctx, func() (map[string]interface{}, error) {
-		got, callErr := common.FetchDriveMeta(runtime, token, docType, false)
-		if callErr != nil {
-			return nil, callErr
-		}
-		title = got.Title
-		return map[string]interface{}{"title": got.Title}, nil
-	})
-	if err != nil {
-		return "", err
-	}
-	return title, nil
-}
-
-func driveInspectCallWithRetry(ctx context.Context, call func() (map[string]interface{}, error)) (map[string]interface{}, error) {
-	var lastErr error
-	for attempt := 0; attempt <= driveInspectRateLimitRetries; attempt++ {
-		data, err := call()
-		if err == nil {
-			return data, nil
-		}
-		lastErr = err
-		if !driveInspectShouldRetry(err) || attempt == driveInspectRateLimitRetries {
-			return nil, err
-		}
-		backoff := driveInspectRetryInitialBackoff * time.Duration(1<<attempt)
-		if waitErr := driveInspectWait(ctx, backoff); waitErr != nil {
-			return nil, waitErr
-		}
-	}
-	return nil, lastErr
-}
-
-func driveInspectShouldRetry(err error) bool {
-	problem, ok := errs.ProblemOf(err)
-	if !ok || problem == nil {
-		return false
-	}
-	return problem.Subtype == errs.SubtypeRateLimit || problem.Code == 99991400 || problem.Retryable
-}
-
-func driveInspectWait(ctx context.Context, d time.Duration) error {
-	if d <= 0 {
-		return nil
-	}
-	select {
-	case <-ctx.Done():
-		return errs.WrapInternal(ctx.Err())
-	case <-driveInspectAfter(d):
-		return nil
-	}
-}
-
-func driveInspectAnnotateError(stage string, err error) error {
-	problem, ok := errs.ProblemOf(err)
-	if !ok || problem == nil {
-		return err
-	}
-	label := map[string]string{
-		"resolve_wiki": "resolve wiki node",
-		"query_meta":   "query document metadata",
-	}[stage]
-	if label == "" {
-		label = stage
-	}
-	problem.Message = fmt.Sprintf("%s failed: %s", label, problem.Message)
-	if strings.TrimSpace(problem.Hint) == "" {
-		switch stage {
-		case "resolve_wiki":
-			problem.Hint = "check that the wiki URL/token is valid and that the current identity can read the wiki node"
-		case "query_meta":
-			problem.Hint = "check that the resolved document still exists and that the current identity can read its metadata"
-		}
-	} else if !strings.Contains(problem.Hint, label) {
-		problem.Hint = label + ": " + problem.Hint
-	}
-	return err
-}

shortcuts/drive/drive_inspect_test.go

@@ -6,13 +6,10 @@ package drive
 import (
 	"context"
 	"encoding/json"
-	"strings"
 	"testing"
-	"time"
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -86,34 +83,6 @@ func TestDriveInspectValidate_BareTokenWithType(t *testing.T) {
 	}
 }
 
-func TestDriveInspectValidate_URLTypeConflict(t *testing.T) {
-	cmd := &cobra.Command{Use: "drive +inspect"}
-	cmd.Flags().String("url", "", "")
-	cmd.Flags().String("type", "", "")
-	_ = cmd.Flags().Set("url", "https://xxx.feishu.cn/docx/doxcnBareToken")
-	_ = cmd.Flags().Set("type", "sheet")
-
-	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
-	err := DriveInspect.Validate(context.Background(), runtime)
-	if err == nil {
-		t.Fatal("expected error for conflicting --type, got nil")
-	}
-}
-
-func TestDriveInspectValidate_BareTokenWithPathFragment(t *testing.T) {
-	cmd := &cobra.Command{Use: "drive +inspect"}
-	cmd.Flags().String("url", "", "")
-	cmd.Flags().String("type", "", "")
-	_ = cmd.Flags().Set("url", "doxcnBareToken/extra")
-	_ = cmd.Flags().Set("type", "docx")
-
-	runtime := common.TestNewRuntimeContext(cmd, &core.CliConfig{})
-	err := DriveInspect.Validate(context.Background(), runtime)
-	if err == nil {
-		t.Fatal("expected error for bare token with path fragment, got nil")
-	}
-}
-
 func TestDriveInspectValidate_ValidDocxURL(t *testing.T) {
 	cmd := &cobra.Command{Use: "drive +inspect"}
 	cmd.Flags().String("url", "", "")
@@ -571,76 +540,6 @@ func TestDriveInspectExecute_BatchQueryError(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for batch_query failure, got nil")
 	}
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed error, got %T", err)
-	}
-	if !strings.Contains(p.Message, "query document metadata failed") {
-		t.Fatalf("message = %q, want query document metadata prefix", p.Message)
-	}
-}
-
-func TestDriveInspectExecute_RetriesRateLimitOnWikiResolve(t *testing.T) {
-	cfg := driveTestConfig()
-	f, stdout, _, reg := cmdutil.TestFactory(t, cfg)
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/get_node",
-		Body: map[string]interface{}{
-			"code": 99991400,
-			"msg":  "request trigger frequency limit",
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/get_node",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{
-				"node": map[string]interface{}{
-					"obj_type":   "docx",
-					"obj_token":  "doxcnUnwrapped",
-					"space_id":   "space123",
-					"node_token": "wikcnNodeToken",
-				},
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/drive/v1/metas/batch_query",
-		Body: map[string]interface{}{
-			"code": 0,
-			"data": map[string]interface{}{
-				"metas": []map[string]interface{}{
-					{"doc_token": "doxcnUnwrapped", "doc_type": "docx", "title": "Wiki Doc"},
-				},
-			},
-		},
-	})
-
-	origAfter := driveInspectAfter
-	driveInspectAfter = func(time.Duration) <-chan time.Time {
-		ch := make(chan time.Time, 1)
-		ch <- time.Now()
-		return ch
-	}
-	defer func() { driveInspectAfter = origAfter }()
-
-	err := mountAndRunDrive(t, DriveInspect, []string{
-		"+inspect",
-		"--url", "https://xxx.feishu.cn/wiki/wikcnABC",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error after retry: %v", err)
-	}
-
-	data := decodeDriveEnvelope(t, stdout)
-	if data["token"] != "doxcnUnwrapped" {
-		t.Fatalf("token = %v, want doxcnUnwrapped", data["token"])
-	}
 }
 
 func TestDriveInspectExecute_PrettyFormat(t *testing.T) {

shortcuts/im/helpers_test.go

@@ -609,9 +609,6 @@ func TestShortcuts(t *testing.T) {
 		"+feed-shortcut-create",
 		"+feed-shortcut-remove",
 		"+feed-shortcut-list",
-		"+feed-group-list",
-		"+feed-group-list-item",
-		"+feed-group-query-item",
 	}
 	if !reflect.DeepEqual(commands, want) {
 		t.Fatalf("Shortcuts() commands = %#v, want %#v", commands, want)

shortcuts/im/im_feed_group_item_test.go

@@ -1,713 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package im
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"io"
-	"net/http"
-	"strconv"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/larksuite/cli/shortcuts/common"
-	"github.com/spf13/cobra"
-)
-
-// recordedFGRequest captures one outbound request for assertion.
-type recordedFGRequest struct {
-	method string
-	path   string
-	query  map[string][]string
-	body   map[string]interface{}
-}
-
-// fgResponder maps a URL path suffix to a JSON response body.
-type fgResponder func(path string, page int) (int, interface{})
-
-// newFGCmd builds a cobra command carrying the shortcut's flags, applying the
-// provided overrides.
-func newFGCmd(t *testing.T, sc common.Shortcut, flags map[string]string) *cobra.Command {
-	t.Helper()
-	cmd := &cobra.Command{Use: sc.Command}
-	for _, fl := range sc.Flags {
-		switch fl.Type {
-		case "bool":
-			cmd.Flags().Bool(fl.Name, fl.Default == "true", fl.Desc)
-		case "int":
-			def := 0
-			if fl.Default != "" {
-				n, _ := strconv.Atoi(fl.Default)
-				def = n
-			}
-			cmd.Flags().Int(fl.Name, def, fl.Desc)
-		default:
-			cmd.Flags().String(fl.Name, fl.Default, fl.Desc)
-		}
-	}
-	if err := cmd.ParseFlags(nil); err != nil {
-		t.Fatalf("ParseFlags() error = %v", err)
-	}
-	for name, val := range flags {
-		if err := cmd.Flags().Set(name, val); err != nil {
-			t.Fatalf("set flag %s=%s: %v", name, val, err)
-		}
-	}
-	return cmd
-}
-
-// newFGRuntime wires a user-identity runtime with the shortcut's flags and an
-// httpmock transport that records requests and replies via the responder.
-func newFGRuntime(t *testing.T, sc common.Shortcut, flags map[string]string, recorded *[]recordedFGRequest, responder fgResponder) *common.RuntimeContext {
-	t.Helper()
-	pageByPath := map[string]int{}
-	rt := shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
-		rec := recordedFGRequest{
-			method: req.Method,
-			path:   req.URL.Path,
-			query:  req.URL.Query(),
-		}
-		if req.Body != nil {
-			data, _ := io.ReadAll(req.Body)
-			if len(data) > 0 {
-				_ = json.Unmarshal(data, &rec.body)
-			}
-		}
-		if recorded != nil {
-			*recorded = append(*recorded, rec)
-		}
-		pageByPath[req.URL.Path]++
-		status, body := 200, interface{}(map[string]interface{}{"code": 0, "data": map[string]interface{}{}})
-		if responder != nil {
-			status, body = responder(req.URL.Path, pageByPath[req.URL.Path])
-		}
-		return shortcutJSONResponse(status, body), nil
-	})
-
-	runtime := newUserShortcutRuntime(t, rt)
-	runtime.Cmd = newFGCmd(t, sc, flags)
-	runtime.Format = "json"
-	return runtime
-}
-
-func wrapData(d map[string]interface{}) map[string]interface{} {
-	return map[string]interface{}{"code": 0, "data": d}
-}
-
-func findFGRequest(reqs []recordedFGRequest, pathSuffix string) *recordedFGRequest {
-	for i := range reqs {
-		if strings.HasSuffix(reqs[i].path, pathSuffix) {
-			return &reqs[i]
-		}
-	}
-	return nil
-}
-
-func firstQueryValue(q map[string][]string, key string) string {
-	if v := q[key]; len(v) > 0 {
-		return v[0]
-	}
-	return ""
-}
-
-// dryRunJSON marshals a DryRunAPI to its wire shape so tests can assert against
-// the public JSON (calls/extra are unexported on the struct).
-func dryRunJSON(t *testing.T, d *common.DryRunAPI) map[string]interface{} {
-	t.Helper()
-	b, err := json.Marshal(d)
-	if err != nil {
-		t.Fatalf("marshal dry-run: %v", err)
-	}
-	var m map[string]interface{}
-	if err := json.Unmarshal(b, &m); err != nil {
-		t.Fatalf("unmarshal dry-run: %v", err)
-	}
-	return m
-}
-
-func dryRunCalls(t *testing.T, d *common.DryRunAPI) []map[string]interface{} {
-	t.Helper()
-	m := dryRunJSON(t, d)
-	raw, _ := m["api"].([]interface{})
-	calls := make([]map[string]interface{}, 0, len(raw))
-	for _, c := range raw {
-		cm, _ := c.(map[string]interface{})
-		calls = append(calls, cm)
-	}
-	return calls
-}
-
-func countFGRequests(reqs []recordedFGRequest, pathSuffix string) int {
-	n := 0
-	for i := range reqs {
-		if strings.HasSuffix(reqs[i].path, pathSuffix) {
-			n++
-		}
-	}
-	return n
-}
-
-// ── list-item: happy path with enrichment of items + deleted_items ──
-
-func TestFeedGroupListItemEnrichesBothLists(t *testing.T) {
-	var reqs []recordedFGRequest
-	runtime := newFGRuntime(t, ImFeedGroupListItem, map[string]string{"feed-group-id": "ofg_x"}, &reqs,
-		func(path string, _ int) (int, interface{}) {
-			switch {
-			case strings.HasSuffix(path, "/list_item"):
-				return 200, wrapData(map[string]interface{}{
-					"items":         []interface{}{map[string]interface{}{"feed_id": "oc_abc", "feed_type": "chat", "update_time": "1767196800000"}},
-					"deleted_items": []interface{}{map[string]interface{}{"feed_id": "oc_def", "feed_type": "chat", "update_time": "1767196800000"}},
-					"page_token":    "",
-					"has_more":      false,
-				})
-			case strings.HasSuffix(path, "/chats/batch_query"):
-				return 200, wrapData(map[string]interface{}{"items": []interface{}{
-					map[string]interface{}{"chat_id": "oc_abc", "name": "Release Team"},
-					map[string]interface{}{"chat_id": "oc_def", "name": "Old Channel"},
-				}})
-			}
-			return 200, wrapData(map[string]interface{}{})
-		})
-
-	if err := ImFeedGroupListItem.Execute(context.Background(), runtime); err != nil {
-		t.Fatalf("Execute returned error: %v", err)
-	}
-
-	list := findFGRequest(reqs, "/list_item")
-	if list == nil {
-		t.Fatal("expected list_item request")
-	}
-	if list.method != http.MethodGet {
-		t.Errorf("list_item method = %s, want GET", list.method)
-	}
-	if !strings.HasSuffix(list.path, "/open-apis/im/v1/groups/ofg_x/list_item") {
-		t.Errorf("list_item path = %s", list.path)
-	}
-	if findFGRequest(reqs, "/chats/batch_query") == nil {
-		t.Error("expected chats/batch_query enrichment request")
-	}
-}
-
-// ── list-item: empty items skips enrichment ──
-
-func TestFeedGroupListItemEmptySkipsEnrichment(t *testing.T) {
-	var reqs []recordedFGRequest
-	runtime := newFGRuntime(t, ImFeedGroupListItem, map[string]string{"feed-group-id": "ofg_x"}, &reqs,
-		func(path string, _ int) (int, interface{}) {
-			if strings.HasSuffix(path, "/list_item") {
-				return 200, wrapData(map[string]interface{}{
-					"items": []interface{}{}, "deleted_items": []interface{}{},
-					"page_token": "", "has_more": false,
-				})
-			}
-			return 200, wrapData(map[string]interface{}{})
-		})
-	if err := ImFeedGroupListItem.Execute(context.Background(), runtime); err != nil {
-		t.Fatalf("Execute error: %v", err)
-	}
-	if findFGRequest(reqs, "/chats/batch_query") != nil {
-		t.Error("did not expect batch_query when there are no items")
-	}
-}
-
-// ── list-item: page-all merges across 2 pages, empty deleted serializes as [] ──
-
-func TestFeedGroupListItemPageAllMerges(t *testing.T) {
-	var reqs []recordedFGRequest
-	runtime := newFGRuntime(t, ImFeedGroupListItem, map[string]string{"feed-group-id": "ofg_x", "page-all": "true"}, &reqs,
-		func(path string, page int) (int, interface{}) {
-			if strings.HasSuffix(path, "/list_item") {
-				if page == 1 {
-					return 200, wrapData(map[string]interface{}{
-						"items":         []interface{}{map[string]interface{}{"feed_id": "oc_a", "feed_type": "chat", "update_time": "1"}},
-						"deleted_items": []interface{}{},
-						"page_token":    "TKN", "has_more": true,
-					})
-				}
-				return 200, wrapData(map[string]interface{}{
-					"items":         []interface{}{map[string]interface{}{"feed_id": "oc_b", "feed_type": "chat", "update_time": "2"}},
-					"deleted_items": []interface{}{},
-					"page_token":    "", "has_more": false,
-				})
-			}
-			if strings.HasSuffix(path, "/chats/batch_query") {
-				return 200, wrapData(map[string]interface{}{"items": []interface{}{
-					map[string]interface{}{"chat_id": "oc_a", "name": "A"},
-					map[string]interface{}{"chat_id": "oc_b", "name": "B"},
-				}})
-			}
-			return 200, wrapData(map[string]interface{}{})
-		})
-	if err := ImFeedGroupListItem.Execute(context.Background(), runtime); err != nil {
-		t.Fatalf("Execute error: %v", err)
-	}
-	if got := countFGRequests(reqs, "/list_item"); got != 2 {
-		t.Errorf("expected 2 list_item requests, got %d", got)
-	}
-	// Second list_item page must carry the continuation token.
-	var second *recordedFGRequest
-	n := 0
-	for i := range reqs {
-		if strings.HasSuffix(reqs[i].path, "/list_item") {
-			n++
-			if n == 2 {
-				second = &reqs[i]
-			}
-		}
-	}
-	if second == nil || firstQueryValue(second.query, "page_token") != "TKN" {
-		t.Errorf("second page token = %q, want TKN", firstQueryValue(second.query, "page_token"))
-	}
-}
-
-// ── list-item: explicit page-token ignores page-all (single page) ──
-
-func TestFeedGroupListItemPageTokenIgnoresPageAll(t *testing.T) {
-	var reqs []recordedFGRequest
-	runtime := newFGRuntime(t, ImFeedGroupListItem, map[string]string{
-		"feed-group-id": "ofg_x", "page-all": "true", "page-token": "SOMETOKEN",
-	}, &reqs, func(path string, _ int) (int, interface{}) {
-		if strings.HasSuffix(path, "/list_item") {
-			return 200, wrapData(map[string]interface{}{
-				"items": []interface{}{}, "deleted_items": []interface{}{},
-				"page_token": "NEXT", "has_more": true,
-			})
-		}
-		return 200, wrapData(map[string]interface{}{})
-	})
-	if err := ImFeedGroupListItem.Execute(context.Background(), runtime); err != nil {
-		t.Fatalf("Execute error: %v", err)
-	}
-	if got := countFGRequests(reqs, "/list_item"); got != 1 {
-		t.Errorf("expected 1 list_item request (page-token wins), got %d", got)
-	}
-	req := findFGRequest(reqs, "/list_item")
-	if got := firstQueryValue(req.query, "page_token"); got != "SOMETOKEN" {
-		t.Errorf("page_token query = %q, want SOMETOKEN", got)
-	}
-}
-
-// ── query-item: builds correct body and enriches ──
-
-func TestFeedGroupQueryItemBuildsBody(t *testing.T) {
-	var reqs []recordedFGRequest
-	runtime := newFGRuntime(t, ImFeedGroupQueryItem, map[string]string{
-		"feed-group-id": "ofg_x", "feed-id": "oc_a,oc_b",
-	}, &reqs, func(path string, _ int) (int, interface{}) {
-		switch {
-		case strings.HasSuffix(path, "/batch_query_item"):
-			return 200, wrapData(map[string]interface{}{
-				"items":         []interface{}{map[string]interface{}{"feed_id": "oc_a", "feed_type": "chat", "update_time": "1"}},
-				"deleted_items": []interface{}{},
-			})
-		case strings.HasSuffix(path, "/chats/batch_query"):
-			return 200, wrapData(map[string]interface{}{"items": []interface{}{
-				map[string]interface{}{"chat_id": "oc_a", "name": "Team A"},
-			}})
-		}
-		return 200, wrapData(map[string]interface{}{})
-	})
-	if err := ImFeedGroupQueryItem.Execute(context.Background(), runtime); err != nil {
-		t.Fatalf("Execute error: %v", err)
-	}
-	req := findFGRequest(reqs, "/batch_query_item")
-	if req == nil {
-		t.Fatal("expected batch_query_item request")
-	}
-	if req.method != http.MethodPost {
-		t.Errorf("method = %s, want POST", req.method)
-	}
-	if !strings.HasSuffix(req.path, "/open-apis/im/v1/groups/ofg_x/batch_query_item") {
-		t.Errorf("path = %s", req.path)
-	}
-	items, ok := req.body["items"].([]interface{})
-	if !ok || len(items) != 2 {
-		t.Fatalf("body items = %#v, want 2 entries", req.body["items"])
-	}
-	first, _ := items[0].(map[string]interface{})
-	if first["feed_id"] != "oc_a" || first["feed_type"] != "chat" {
-		t.Errorf("first item = %#v", first)
-	}
-}
-
-// ── table output: renders feed_id / chat_name / update_time + summary lines ──
-
-func TestFeedGroupListItemTableOutput(t *testing.T) {
-	runtime := newFGRuntime(t, ImFeedGroupListItem, map[string]string{"feed-group-id": "ofg_x"}, nil,
-		func(path string, _ int) (int, interface{}) {
-			switch {
-			case strings.HasSuffix(path, "/list_item"):
-				return 200, wrapData(map[string]interface{}{
-					"items":         []interface{}{map[string]interface{}{"feed_id": "oc_abc", "feed_type": "chat", "update_time": "1767196800000"}},
-					"deleted_items": []interface{}{map[string]interface{}{"feed_id": "oc_def", "feed_type": "chat", "update_time": "1767196800000"}},
-					"page_token":    "TKN", "has_more": true,
-				})
-			case strings.HasSuffix(path, "/chats/batch_query"):
-				return 200, wrapData(map[string]interface{}{"items": []interface{}{
-					map[string]interface{}{"chat_id": "oc_abc", "name": "Release Team"},
-				}})
-			}
-			return 200, wrapData(map[string]interface{}{})
-		})
-	runtime.Format = "pretty"
-
-	if err := ImFeedGroupListItem.Execute(context.Background(), runtime); err != nil {
-		t.Fatalf("Execute error: %v", err)
-	}
-	out, _ := runtime.Factory.IOStreams.Out.(*bytes.Buffer)
-	if out == nil {
-		t.Fatal("stdout buffer missing")
-	}
-	got := out.String()
-	for _, want := range []string{"feed_id", "chat_name", "update_time", "oc_abc", "Release Team", "1 item(s)", "more available", "(1 deleted)"} {
-		if !strings.Contains(got, want) {
-			t.Errorf("table output missing %q; got:\n%s", want, got)
-		}
-	}
-	// update_time must be rendered human-readable (RFC3339), not as raw Unix millis.
-	if strings.Contains(got, "1767196800000") {
-		t.Errorf("table output should not contain raw millis timestamp; got:\n%s", got)
-	}
-	wantTime := time.UnixMilli(1767196800000).Local().Format(time.RFC3339)
-	if !strings.Contains(got, wantTime) {
-		t.Errorf("table output should contain formatted update_time %q; got:\n%s", wantTime, got)
-	}
-}
-
-// ── enrichment graceful degradation: unresolved feed_id keeps no chat_name ──
-
-func TestEnrichFeedGroupItemsGracefulDegradation(t *testing.T) {
-	runtime := newFGRuntime(t, ImFeedGroupQueryItem, map[string]string{
-		"feed-group-id": "ofg_x", "feed-id": "oc_known",
-	}, nil, func(path string, _ int) (int, interface{}) {
-		if strings.HasSuffix(path, "/chats/batch_query") {
-			// Only oc_known resolves; oc_gone is absent.
-			return 200, wrapData(map[string]interface{}{"items": []interface{}{
-				map[string]interface{}{"chat_id": "oc_known", "name": "Known"},
-			}})
-		}
-		return 200, wrapData(map[string]interface{}{})
-	})
-	data := map[string]any{
-		"items": []any{
-			map[string]any{"feed_id": "oc_known", "feed_type": "chat"},
-			map[string]any{"feed_id": "oc_gone", "feed_type": "chat"},
-		},
-		"deleted_items": []any{},
-	}
-	enrichFeedGroupItemsChatName(runtime, data)
-	items := data["items"].([]any)
-	known := items[0].(map[string]any)
-	gone := items[1].(map[string]any)
-	if known["chat_name"] != "Known" {
-		t.Errorf("oc_known chat_name = %v, want Known", known["chat_name"])
-	}
-	if _, present := gone["chat_name"]; present {
-		t.Errorf("oc_gone should not have chat_name, got %v", gone["chat_name"])
-	}
-}
-
-// ── validation errors ──
-
-func TestFeedGroupValidationErrors(t *testing.T) {
-	cases := []struct {
-		name  string
-		sc    common.Shortcut
-		flags map[string]string
-		want  string
-	}{
-		{"list missing feed-group-id", ImFeedGroupListItem, map[string]string{}, "--feed-group-id is required"},
-		{"list bad page-size", ImFeedGroupListItem, map[string]string{"feed-group-id": "ofg_x", "page-size": "0"}, "--page-size must be an integer between 1 and 50"},
-		{"list bad page-limit", ImFeedGroupListItem, map[string]string{"feed-group-id": "ofg_x", "page-limit": "2000"}, "--page-limit must be an integer between 1 and 1000"},
-		{"list bad start-time", ImFeedGroupListItem, map[string]string{"feed-group-id": "ofg_x", "start-time": "notnum"}, "--start-time must be Unix milliseconds"},
-		{"list bad end-time", ImFeedGroupListItem, map[string]string{"feed-group-id": "ofg_x", "end-time": "notnum"}, "--end-time must be Unix milliseconds"},
-		{"query missing feed-group-id", ImFeedGroupQueryItem, map[string]string{"feed-id": "oc_a"}, "--feed-group-id is required"},
-		{"query missing feed-id", ImFeedGroupQueryItem, map[string]string{"feed-group-id": "ofg_x"}, "--feed-id is required (comma-separated chat IDs)"},
-		{"query blank feed-id tokens", ImFeedGroupQueryItem, map[string]string{"feed-group-id": "ofg_x", "feed-id": ", ,"}, "--feed-id is required (comma-separated chat IDs)"},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			runtime := newFGRuntime(t, tc.sc, tc.flags, nil, nil)
-			err := tc.sc.Validate(context.Background(), runtime)
-			if err == nil {
-				t.Fatalf("expected validation error %q, got nil", tc.want)
-			}
-			if !strings.Contains(err.Error(), tc.want) {
-				t.Errorf("error = %q, want contains %q", err.Error(), tc.want)
-			}
-		})
-	}
-}
-
-// ── dry-run shapes ──
-
-func TestFeedGroupListItemDryRun(t *testing.T) {
-	runtime := newFGRuntime(t, ImFeedGroupListItem, map[string]string{
-		"feed-group-id": "ofg_x", "page-size": "10", "page-token": "TKN", "start-time": "100", "end-time": "200",
-	}, nil, nil)
-	d := ImFeedGroupListItem.DryRun(context.Background(), runtime)
-	calls := dryRunCalls(t, d)
-	if len(calls) != 1 {
-		t.Fatalf("expected 1 call, got %d", len(calls))
-	}
-	if calls[0]["method"] != "GET" {
-		t.Errorf("method = %v, want GET", calls[0]["method"])
-	}
-	if url, _ := calls[0]["url"].(string); !strings.HasSuffix(url, "/groups/ofg_x/list_item") {
-		t.Errorf("url = %s", url)
-	}
-	params, _ := calls[0]["params"].(map[string]interface{})
-	for key, want := range map[string]string{
-		"page_size": "10", "page_token": "TKN", "start_time": "100", "end_time": "200",
-	} {
-		if params[key] != want {
-			t.Errorf("params %s = %v, want %s", key, params[key], want)
-		}
-	}
-	if desc, _ := calls[0]["desc"].(string); !strings.Contains(desc, "im:chat:read") {
-		t.Errorf("desc = %q, want chat_name enrichment note", desc)
-	}
-}
-
-func TestFeedGroupListItemDryRunValidationError(t *testing.T) {
-	runtime := newFGRuntime(t, ImFeedGroupListItem, map[string]string{}, nil, nil)
-	d := ImFeedGroupListItem.DryRun(context.Background(), runtime)
-	m := dryRunJSON(t, d)
-	errMsg, _ := m["error"].(string)
-	if errMsg == "" {
-		t.Fatalf("expected error in dry-run output, got %#v", m)
-	}
-	if !strings.Contains(errMsg, "--feed-group-id is required") {
-		t.Errorf("error = %v", errMsg)
-	}
-}
-
-func TestFeedGroupQueryItemDryRun(t *testing.T) {
-	runtime := newFGRuntime(t, ImFeedGroupQueryItem, map[string]string{
-		"feed-group-id": "ofg_x", "feed-id": "oc_a,oc_b",
-	}, nil, nil)
-	d := ImFeedGroupQueryItem.DryRun(context.Background(), runtime)
-	calls := dryRunCalls(t, d)
-	if len(calls) != 1 {
-		t.Fatalf("expected 1 call, got %d", len(calls))
-	}
-	if calls[0]["method"] != "POST" {
-		t.Errorf("method = %v, want POST", calls[0]["method"])
-	}
-	if url, _ := calls[0]["url"].(string); !strings.HasSuffix(url, "/groups/ofg_x/batch_query_item") {
-		t.Errorf("url = %s", url)
-	}
-	body, _ := calls[0]["body"].(map[string]interface{})
-	items, _ := body["items"].([]interface{})
-	if len(items) != 2 {
-		t.Fatalf("dry-run body items = %#v, want 2", body["items"])
-	}
-}
-
-func TestFeedGroupQueryItemDryRunValidationError(t *testing.T) {
-	runtime := newFGRuntime(t, ImFeedGroupQueryItem, map[string]string{"feed-group-id": "ofg_x"}, nil, nil)
-	d := ImFeedGroupQueryItem.DryRun(context.Background(), runtime)
-	m := dryRunJSON(t, d)
-	if errMsg, _ := m["error"].(string); errMsg == "" {
-		t.Fatalf("expected error in dry-run output, got %#v", m)
-	}
-}
-
-// ── list-item: time-window flags reach the query ──
-
-func TestFeedGroupListItemTimeWindowQueryParams(t *testing.T) {
-	var reqs []recordedFGRequest
-	runtime := newFGRuntime(t, ImFeedGroupListItem, map[string]string{
-		"feed-group-id": "ofg_x", "start-time": "100", "end-time": "200",
-	}, &reqs, func(path string, _ int) (int, interface{}) {
-		if strings.HasSuffix(path, "/list_item") {
-			return 200, wrapData(map[string]interface{}{
-				"items": []interface{}{}, "deleted_items": []interface{}{},
-				"page_token": "", "has_more": false,
-			})
-		}
-		return 200, wrapData(map[string]interface{}{})
-	})
-	if err := ImFeedGroupListItem.Execute(context.Background(), runtime); err != nil {
-		t.Fatalf("Execute error: %v", err)
-	}
-	req := findFGRequest(reqs, "/list_item")
-	if req == nil {
-		t.Fatal("expected list_item request")
-	}
-	if got := firstQueryValue(req.query, "start_time"); got != "100" {
-		t.Errorf("start_time query = %q, want 100", got)
-	}
-	if got := firstQueryValue(req.query, "end_time"); got != "200" {
-		t.Errorf("end_time query = %q, want 200", got)
-	}
-}
-
-// ── list-item: infinite-loop guard + defensive page-limit clamping ──
-
-func TestFeedGroupListItemPageAllStopsOnRepeatedToken(t *testing.T) {
-	for _, tc := range []struct {
-		name      string
-		pageLimit string
-	}{
-		{"limit clamped up from 0", "0"},
-		{"limit clamped down from 1001", "1001"},
-	} {
-		t.Run(tc.name, func(t *testing.T) {
-			var reqs []recordedFGRequest
-			runtime := newFGRuntime(t, ImFeedGroupListItem, map[string]string{
-				"feed-group-id": "ofg_x", "page-all": "true", "page-limit": tc.pageLimit,
-				"start-time": "100", "end-time": "200",
-			}, &reqs, func(path string, _ int) (int, interface{}) {
-				if strings.HasSuffix(path, "/list_item") {
-					return 200, wrapData(map[string]interface{}{
-						"items":         []interface{}{map[string]interface{}{"feed_id": "oc_a", "feed_type": "chat", "update_time": "1"}},
-						"deleted_items": []interface{}{},
-						"page_token":    "SAME", "has_more": true,
-					})
-				}
-				return 200, wrapData(map[string]interface{}{})
-			})
-			runtime.Format = "pretty" // exercise the page-all table-render path too
-			if err := ImFeedGroupListItem.Execute(context.Background(), runtime); err != nil {
-				t.Fatalf("Execute error: %v", err)
-			}
-			if got := countFGRequests(reqs, "/list_item"); got != 2 {
-				t.Errorf("expected 2 list_item requests (stop on repeated token), got %d", got)
-			}
-			errOut, _ := runtime.Factory.IOStreams.ErrOut.(*bytes.Buffer)
-			if !strings.Contains(errOut.String(), "page_token did not change") {
-				t.Errorf("stderr missing loop warning; got:\n%s", errOut.String())
-			}
-		})
-	}
-}
-
-// ── list-item: API errors surface from both Execute paths ──
-
-func TestFeedGroupListItemAPIError(t *testing.T) {
-	for _, tc := range []struct {
-		name  string
-		flags map[string]string
-	}{
-		{"single page", map[string]string{"feed-group-id": "ofg_x"}},
-		{"page-all", map[string]string{"feed-group-id": "ofg_x", "page-all": "true"}},
-	} {
-		t.Run(tc.name, func(t *testing.T) {
-			runtime := newFGRuntime(t, ImFeedGroupListItem, tc.flags, nil,
-				func(_ string, _ int) (int, interface{}) {
-					return 200, map[string]interface{}{"code": 99999, "msg": "boom"}
-				})
-			if err := ImFeedGroupListItem.Execute(context.Background(), runtime); err == nil {
-				t.Fatal("expected API error, got nil")
-			}
-		})
-	}
-}
-
-// ── enrichment: total resolution failure warns on stderr, nil data is a no-op ──
-
-func TestEnrichFeedGroupItemsWarnsWhenResolutionFails(t *testing.T) {
-	runtime := newFGRuntime(t, ImFeedGroupQueryItem, map[string]string{}, nil,
-		func(path string, _ int) (int, interface{}) {
-			if strings.HasSuffix(path, "/chats/batch_query") {
-				return 200, map[string]interface{}{"code": 99999, "msg": "boom"}
-			}
-			return 200, wrapData(map[string]interface{}{})
-		})
-
-	// nil data must not panic.
-	enrichFeedGroupItemsChatName(runtime, nil)
-
-	data := map[string]any{
-		"items":         []any{map[string]any{"feed_id": "oc_a", "feed_type": "chat"}},
-		"deleted_items": []any{},
-	}
-	enrichFeedGroupItemsChatName(runtime, data)
-
-	item := data["items"].([]any)[0].(map[string]any)
-	if _, present := item["chat_name"]; present {
-		t.Errorf("chat_name should be absent when resolution fails, got %v", item["chat_name"])
-	}
-	errOut, _ := runtime.Factory.IOStreams.ErrOut.(*bytes.Buffer)
-	if !strings.Contains(errOut.String(), "could not resolve chat names") {
-		t.Errorf("stderr missing resolution warning; got:\n%s", errOut.String())
-	}
-}
-
-// ── query-item: Execute error paths ──
-
-func TestFeedGroupQueryItemExecuteErrors(t *testing.T) {
-	t.Run("invalid flags", func(t *testing.T) {
-		runtime := newFGRuntime(t, ImFeedGroupQueryItem, map[string]string{"feed-group-id": "ofg_x"}, nil, nil)
-		if err := ImFeedGroupQueryItem.Execute(context.Background(), runtime); err == nil {
-			t.Fatal("expected validation error from Execute, got nil")
-		}
-	})
-	t.Run("api error", func(t *testing.T) {
-		runtime := newFGRuntime(t, ImFeedGroupQueryItem, map[string]string{
-			"feed-group-id": "ofg_x", "feed-id": "oc_a",
-		}, nil, func(_ string, _ int) (int, interface{}) {
-			return 200, map[string]interface{}{"code": 99999, "msg": "boom"}
-		})
-		if err := ImFeedGroupQueryItem.Execute(context.Background(), runtime); err == nil {
-			t.Fatal("expected API error, got nil")
-		}
-	})
-}
-
-// ── formatFeedGroupUpdateTime: empty / non-numeric inputs pass through ──
-
-func TestFormatFeedGroupUpdateTime(t *testing.T) {
-	if got := formatFeedGroupUpdateTime(""); got != "" {
-		t.Errorf("empty input = %q, want empty passthrough", got)
-	}
-	if got := formatFeedGroupUpdateTime("not-millis"); got != "not-millis" {
-		t.Errorf("non-numeric input = %q, want raw passthrough", got)
-	}
-	want := time.UnixMilli(1767196800000).Local().Format(time.RFC3339)
-	if got := formatFeedGroupUpdateTime("1767196800000"); got != want {
-		t.Errorf("millis input = %q, want %q", got, want)
-	}
-}
-
-// ── query-item: pretty table output renders enriched items ──
-
-func TestFeedGroupQueryItemTableOutput(t *testing.T) {
-	runtime := newFGRuntime(t, ImFeedGroupQueryItem, map[string]string{
-		"feed-group-id": "ofg_x", "feed-id": "oc_a",
-	}, nil, func(path string, _ int) (int, interface{}) {
-		switch {
-		case strings.HasSuffix(path, "/batch_query_item"):
-			return 200, wrapData(map[string]interface{}{
-				"items":         []interface{}{map[string]interface{}{"feed_id": "oc_a", "feed_type": "chat", "update_time": "1767196800000"}},
-				"deleted_items": []interface{}{},
-			})
-		case strings.HasSuffix(path, "/chats/batch_query"):
-			return 200, wrapData(map[string]interface{}{"items": []interface{}{
-				map[string]interface{}{"chat_id": "oc_a", "name": "Team A"},
-			}})
-		}
-		return 200, wrapData(map[string]interface{}{})
-	})
-	runtime.Format = "pretty"
-
-	if err := ImFeedGroupQueryItem.Execute(context.Background(), runtime); err != nil {
-		t.Fatalf("Execute error: %v", err)
-	}
-	out, _ := runtime.Factory.IOStreams.Out.(*bytes.Buffer)
-	if out == nil {
-		t.Fatal("stdout buffer missing")
-	}
-	got := out.String()
-	for _, want := range []string{"oc_a", "Team A", "1 item(s)"} {
-		if !strings.Contains(got, want) {
-			t.Errorf("table output missing %q; got:\n%s", want, got)
-		}
-	}
-}

shortcuts/im/im_feed_group_items.go

@@ -1,140 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package im
-
-import (
-	"fmt"
-	"io"
-	"strconv"
-	"time"
-
-	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-const (
-	// feedGroupReadScope is required to read feed-group items.
-	feedGroupReadScope = "im:feed_group_v1:read"
-	// chatReadScope is required to resolve chat_name from feed_id via chats/batch_query.
-	chatReadScope = "im:chat:read"
-)
-
-// enrichFeedGroupItemsChatName resolves a human-readable chat_name for each feed
-// card in data["items"] and data["deleted_items"] using chats/batch_query.
-//
-// The feed_id of a v1 feed card is always a chat ID (oc_xxx), so the chat's name
-// is the natural display label. Resolution degrades gracefully: any feed_id that
-// cannot be resolved simply keeps no chat_name key, and the function never returns
-// an error or alters the exit code.
-//
-// NOTE: This mutates the item maps in place by adding a "chat_name" key.
-func enrichFeedGroupItemsChatName(rt *common.RuntimeContext, data map[string]any) {
-	if data == nil {
-		return
-	}
-
-	items, _ := data["items"].([]any)
-	deletedItems, _ := data["deleted_items"].([]any)
-
-	// Collect deduped, ordered feed_id strings from both lists.
-	ids := make([]string, 0, len(items)+len(deletedItems))
-	seen := make(map[string]bool)
-	collect := func(list []any) {
-		for _, it := range list {
-			m, _ := it.(map[string]any)
-			if m == nil {
-				continue
-			}
-			id, _ := m["feed_id"].(string)
-			if id == "" || seen[id] {
-				continue
-			}
-			seen[id] = true
-			ids = append(ids, id)
-		}
-	}
-	collect(items)
-	collect(deletedItems)
-
-	if len(ids) == 0 {
-		return
-	}
-
-	contexts := batchQueryChatContexts(rt, ids)
-	if len(contexts) == 0 {
-		// We had feed_ids to resolve but got nothing back — most likely the
-		// chats/batch_query call failed (it degrades silently). Tell the user so
-		// an empty chat_name column is not mistaken for chats that simply have no name.
-		fmt.Fprintf(rt.IO().ErrOut, "warning: could not resolve chat names for %d feed(s); chat_name will be empty\n", len(ids))
-		return
-	}
-
-	apply := func(list []any) {
-		for _, it := range list {
-			m, _ := it.(map[string]any)
-			if m == nil {
-				continue
-			}
-			id, _ := m["feed_id"].(string)
-			if id == "" {
-				continue
-			}
-			if ctx, ok := contexts[id]; ok {
-				if name, _ := ctx["name"].(string); name != "" {
-					m["chat_name"] = name
-				}
-			}
-		}
-	}
-	apply(items)
-	apply(deletedItems)
-}
-
-// renderFeedGroupItemsTable prints the active items[] as a table (feed_id /
-// chat_name / update_time), followed by a summary line. When hasMore is true a
-// pagination hint is appended; when there are deleted items their count is noted.
-func renderFeedGroupItemsTable(w io.Writer, data map[string]any, hasMore bool) {
-	items, _ := data["items"].([]any)
-	rows := make([]map[string]interface{}, 0, len(items))
-	for _, it := range items {
-		m, _ := it.(map[string]any)
-		if m == nil {
-			continue
-		}
-		chatName, _ := m["chat_name"].(string)
-		updateTime, _ := m["update_time"].(string)
-		feedID, _ := m["feed_id"].(string)
-		rows = append(rows, map[string]interface{}{
-			"feed_id":     feedID,
-			"chat_name":   chatName,
-			"update_time": formatFeedGroupUpdateTime(updateTime),
-		})
-	}
-	output.PrintTable(w, rows)
-
-	moreHint := ""
-	if hasMore {
-		moreHint = " (more available, use --page-token to fetch next page)"
-	}
-	fmt.Fprintf(w, "\n%d item(s)%s\n", len(items), moreHint)
-
-	if deleted, _ := data["deleted_items"].([]any); len(deleted) > 0 {
-		fmt.Fprintf(w, "(%d deleted)\n", len(deleted))
-	}
-}
-
-// formatFeedGroupUpdateTime renders a Unix-millisecond timestamp string as a
-// human-readable local time for the pretty table. The raw value is returned
-// unchanged when it is empty or not a valid millisecond integer, so JSON output
-// (which never calls this) keeps the original wire value.
-func formatFeedGroupUpdateTime(raw string) string {
-	if raw == "" {
-		return raw
-	}
-	ms, err := strconv.ParseInt(raw, 10, 64)
-	if err != nil {
-		return raw
-	}
-	return time.UnixMilli(ms).Local().Format(time.RFC3339)
-}

shortcuts/im/im_feed_group_list.go

@@ -1,234 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package im
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"strconv"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/shortcuts/common"
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
-)
-
-const feedGroupListPath = "/open-apis/im/v1/groups"
-
-// ImFeedGroupList provides the +feed-group-list shortcut: it lists the caller's
-// feed groups (tags) with auto-pagination that correctly merges BOTH the live
-// (groups) and soft-deleted (deleted_groups) lists across pages.
-//
-// The raw `feed.groups list --page-all` goes through the generic paginator,
-// which follows only one array field and silently drops the other list's later
-// pages; this shortcut paginates the dual-list response itself.
-var ImFeedGroupList = common.Shortcut{
-	Service:     "im",
-	Command:     "+feed-group-list",
-	Description: "List the caller's feed groups (tags); user-only; supports `--page-all` auto-pagination",
-	Risk:        "read",
-	UserScopes:  []string{feedGroupReadScope},
-	AuthTypes:   []string{"user"},
-	HasFormat:   true,
-	Flags: []common.Flag{
-		{Name: "page-size", Type: "int", Default: "50", Desc: "page size (1-50)"},
-		{Name: "page-token", Desc: "pagination token for next page"},
-		{Name: "page-all", Type: "bool", Desc: "automatically paginate through all pages"},
-		{Name: "page-limit", Type: "int", Default: "20", Desc: "max pages when auto-pagination is enabled (default 20, max 1000)"},
-		{Name: "start-time", Desc: "update-time window start (Unix milliseconds as a decimal string)"},
-		{Name: "end-time", Desc: "update-time window end (Unix milliseconds as a decimal string)"},
-	},
-	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return validateFeedGroupListPageOptions(runtime)
-	},
-	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		if err := validateFeedGroupListPageOptions(runtime); err != nil {
-			return common.NewDryRunAPI().Set("error", err.Error())
-		}
-		return common.NewDryRunAPI().
-			GET(feedGroupListPath).
-			Params(feedGroupListGroupsDryRunParams(runtime))
-	},
-	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		// When --page-token is explicitly provided, the user wants a specific
-		// page — no auto-pagination regardless of --page-all.
-		if runtime.Bool("page-all") && !runtime.Cmd.Flags().Changed("page-token") {
-			return executeFeedGroupListGroupsAllPages(runtime)
-		}
-
-		data, err := runtime.DoAPIJSONTyped("GET", feedGroupListPath, feedGroupListGroupsQuery(runtime), nil)
-		if err != nil {
-			return err
-		}
-
-		hasMore, _ := data["has_more"].(bool)
-		runtime.OutFormat(data, nil, func(w io.Writer) {
-			renderFeedGroupsTable(w, data, hasMore)
-		})
-		return nil
-	},
-}
-
-func validateFeedGroupListPageOptions(rt *common.RuntimeContext) error {
-	if n := rt.Int("page-size"); n < 1 || n > 50 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-size must be an integer between 1 and 50").WithParam("--page-size")
-	}
-	if n := rt.Int("page-limit"); n < 1 || n > 1000 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-limit must be an integer between 1 and 1000").WithParam("--page-limit")
-	}
-	if v := rt.Str("start-time"); v != "" {
-		if _, err := strconv.ParseInt(v, 10, 64); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--start-time must be Unix milliseconds (a decimal integer string)").WithParam("--start-time")
-		}
-	}
-	if v := rt.Str("end-time"); v != "" {
-		if _, err := strconv.ParseInt(v, 10, 64); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end-time must be Unix milliseconds (a decimal integer string)").WithParam("--end-time")
-		}
-	}
-	return nil
-}
-
-// feedGroupListGroupsQuery builds the query parameters. page_token is always
-// sent (empty string = first page) because the groups endpoint rejects requests
-// that omit it (HTTP 400 "Missing required parameter: page_token").
-func feedGroupListGroupsQuery(rt *common.RuntimeContext) larkcore.QueryParams {
-	params := larkcore.QueryParams{
-		"page_size":  []string{strconv.Itoa(rt.Int("page-size"))},
-		"page_token": []string{rt.Str("page-token")},
-	}
-	if start := rt.Str("start-time"); start != "" {
-		params["start_time"] = []string{start}
-	}
-	if end := rt.Str("end-time"); end != "" {
-		params["end_time"] = []string{end}
-	}
-	return params
-}
-
-// feedGroupListGroupsDryRunParams mirrors feedGroupListGroupsQuery for dry-run display.
-func feedGroupListGroupsDryRunParams(rt *common.RuntimeContext) map[string]any {
-	params := map[string]any{
-		"page_size":  strconv.Itoa(rt.Int("page-size")),
-		"page_token": rt.Str("page-token"),
-	}
-	if start := rt.Str("start-time"); start != "" {
-		params["start_time"] = start
-	}
-	if end := rt.Str("end-time"); end != "" {
-		params["end_time"] = end
-	}
-	return params
-}
-
-// executeFeedGroupListGroupsAllPages fetches all pages and merges both the live
-// (groups) and soft-deleted (deleted_groups) lists into a single response. It
-// merges each array independently so neither list loses its later pages.
-func executeFeedGroupListGroupsAllPages(rt *common.RuntimeContext) error {
-	maxPages := rt.Int("page-limit")
-	if maxPages < 1 {
-		maxPages = 20
-	}
-	if maxPages > 1000 {
-		maxPages = 1000
-	}
-
-	// Use make([]any, 0) so empty arrays serialize as [] not null.
-	allGroups := make([]any, 0)
-	allDeletedGroups := make([]any, 0)
-	var lastHasMore bool
-	var lastPageToken string
-	prevPageToken := "__START__"
-
-	for page := 0; page < maxPages; page++ {
-		// page_token is always sent (empty on the first page) — the groups
-		// endpoint rejects requests that omit it.
-		params := larkcore.QueryParams{
-			"page_size":  []string{strconv.Itoa(rt.Int("page-size"))},
-			"page_token": []string{""},
-		}
-		if page > 0 {
-			params["page_token"] = []string{lastPageToken}
-		}
-		if start := rt.Str("start-time"); start != "" {
-			params["start_time"] = []string{start}
-		}
-		if end := rt.Str("end-time"); end != "" {
-			params["end_time"] = []string{end}
-		}
-
-		data, err := rt.DoAPIJSONTyped("GET", feedGroupListPath, params, nil)
-		if err != nil {
-			return err
-		}
-
-		if v, ok := data["groups"].([]any); ok {
-			allGroups = append(allGroups, v...)
-		}
-		if v, ok := data["deleted_groups"].([]any); ok {
-			allDeletedGroups = append(allDeletedGroups, v...)
-		}
-
-		lastHasMore, _ = data["has_more"].(bool)
-		lastPageToken, _ = data["page_token"].(string)
-
-		fmt.Fprintf(rt.IO().ErrOut, "page %d: %d groups, %d deleted\n",
-			page+1, len(allGroups), len(allDeletedGroups))
-
-		if !lastHasMore || lastPageToken == "" {
-			break
-		}
-		if lastPageToken == prevPageToken {
-			fmt.Fprintf(rt.IO().ErrOut, "warning: page_token did not change, stopping pagination to avoid infinite loop\n")
-			break
-		}
-		prevPageToken = lastPageToken
-	}
-
-	merged := map[string]any{
-		"groups":         allGroups,
-		"deleted_groups": allDeletedGroups,
-		"has_more":       lastHasMore,
-		"page_token":     lastPageToken,
-	}
-
-	rt.OutFormat(merged, nil, func(w io.Writer) {
-		renderFeedGroupsTable(w, merged, lastHasMore)
-	})
-	return nil
-}
-
-// renderFeedGroupsTable prints the active groups[] as a table (group_id / name /
-// type), followed by a summary line. When hasMore is true a pagination hint is
-// appended; when there are deleted groups their count is noted.
-func renderFeedGroupsTable(w io.Writer, data map[string]any, hasMore bool) {
-	groups, _ := data["groups"].([]any)
-	rows := make([]map[string]interface{}, 0, len(groups))
-	for _, g := range groups {
-		m, _ := g.(map[string]any)
-		if m == nil {
-			continue
-		}
-		id, _ := m["group_id"].(string)
-		name, _ := m["name"].(string)
-		typ, _ := m["type"].(string)
-		rows = append(rows, map[string]interface{}{
-			"group_id": id,
-			"name":     name,
-			"type":     typ,
-		})
-	}
-	output.PrintTable(w, rows)
-
-	moreHint := ""
-	if hasMore {
-		moreHint = " (more available, use --page-token to fetch next page)"
-	}
-	fmt.Fprintf(w, "\n%d group(s)%s\n", len(groups), moreHint)
-
-	if deleted, _ := data["deleted_groups"].([]any); len(deleted) > 0 {
-		fmt.Fprintf(w, "(%d deleted)\n", len(deleted))
-	}
-}

shortcuts/im/im_feed_group_list_item.go

@@ -1,207 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package im
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"strconv"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/shortcuts/common"
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
-)
-
-// ImFeedGroupListItem provides the +feed-group-list-item shortcut: it lists the
-// feed cards inside one feed group and enriches each item with chat_name resolved
-// from its feed_id.
-var ImFeedGroupListItem = common.Shortcut{
-	Service:     "im",
-	Command:     "+feed-group-list-item",
-	Description: "List feed cards in a feed group (tag); user-only; enriches each item with chat_name resolved from feed_id; supports --page-all auto-pagination",
-	Risk:        "read",
-	UserScopes:  []string{feedGroupReadScope, chatReadScope},
-	AuthTypes:   []string{"user"},
-	HasFormat:   true,
-	Flags: []common.Flag{
-		{Name: "feed-group-id", Desc: "feed group ID (ofg_xxx); path parameter (required)"},
-		{Name: "page-size", Type: "int", Default: "50", Desc: "page size (1-50)"},
-		{Name: "page-token", Desc: "pagination token for next page"},
-		{Name: "page-all", Type: "bool", Desc: "automatically paginate through all pages"},
-		{Name: "page-limit", Type: "int", Default: "20", Desc: "max pages when auto-pagination is enabled (default 20, max 1000)"},
-		{Name: "start-time", Desc: "update-time window start (Unix milliseconds as a decimal string)"},
-		{Name: "end-time", Desc: "update-time window end (Unix milliseconds as a decimal string)"},
-	},
-	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		return validateFeedGroupListOptions(runtime)
-	},
-	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		if err := validateFeedGroupListOptions(runtime); err != nil {
-			return common.NewDryRunAPI().Set("error", err.Error())
-		}
-		return common.NewDryRunAPI().
-			GET(feedGroupListItemPath(runtime)).
-			Params(feedGroupListDryRunParams(runtime)).
-			Desc("will also POST /open-apis/im/v1/chats/batch_query to resolve chat_name from feed_id; requires im:chat:read")
-	},
-	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		// When --page-token is explicitly provided, the user wants a specific page —
-		// no auto-pagination regardless of --page-all.
-		if runtime.Bool("page-all") && !runtime.Cmd.Flags().Changed("page-token") {
-			return executeFeedGroupListAllPages(runtime)
-		}
-
-		data, err := runtime.DoAPIJSONTyped("GET", feedGroupListItemPath(runtime), feedGroupListQuery(runtime), nil)
-		if err != nil {
-			return err
-		}
-		enrichFeedGroupItemsChatName(runtime, data)
-
-		hasMore, _ := data["has_more"].(bool)
-		runtime.OutFormat(data, nil, func(w io.Writer) {
-			renderFeedGroupItemsTable(w, data, hasMore)
-		})
-		return nil
-	},
-}
-
-func validateFeedGroupListOptions(rt *common.RuntimeContext) error {
-	if rt.Str("feed-group-id") == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--feed-group-id is required").WithParam("--feed-group-id")
-	}
-	if n := rt.Int("page-size"); n < 1 || n > 50 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-size must be an integer between 1 and 50").WithParam("--page-size")
-	}
-	if n := rt.Int("page-limit"); n < 1 || n > 1000 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-limit must be an integer between 1 and 1000").WithParam("--page-limit")
-	}
-	if v := rt.Str("start-time"); v != "" {
-		if _, err := strconv.ParseInt(v, 10, 64); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--start-time must be Unix milliseconds (a decimal integer string)").WithParam("--start-time")
-		}
-	}
-	if v := rt.Str("end-time"); v != "" {
-		if _, err := strconv.ParseInt(v, 10, 64); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end-time must be Unix milliseconds (a decimal integer string)").WithParam("--end-time")
-		}
-	}
-	return nil
-}
-
-// feedGroupListItemPath builds the list_item endpoint path with the feed_group_id
-// segment safely encoded.
-func feedGroupListItemPath(rt *common.RuntimeContext) string {
-	return "/open-apis/im/v1/groups/" + validate.EncodePathSegment(rt.Str("feed-group-id")) + "/list_item"
-}
-
-// feedGroupListQuery builds the query parameters, sending only non-empty values.
-func feedGroupListQuery(rt *common.RuntimeContext) larkcore.QueryParams {
-	params := larkcore.QueryParams{
-		"page_size": []string{strconv.Itoa(rt.Int("page-size"))},
-	}
-	if token := rt.Str("page-token"); token != "" {
-		params["page_token"] = []string{token}
-	}
-	if start := rt.Str("start-time"); start != "" {
-		params["start_time"] = []string{start}
-	}
-	if end := rt.Str("end-time"); end != "" {
-		params["end_time"] = []string{end}
-	}
-	return params
-}
-
-// feedGroupListDryRunParams mirrors feedGroupListQuery for dry-run display.
-func feedGroupListDryRunParams(rt *common.RuntimeContext) map[string]any {
-	params := map[string]any{
-		"page_size": strconv.Itoa(rt.Int("page-size")),
-	}
-	if token := rt.Str("page-token"); token != "" {
-		params["page_token"] = token
-	}
-	if start := rt.Str("start-time"); start != "" {
-		params["start_time"] = start
-	}
-	if end := rt.Str("end-time"); end != "" {
-		params["end_time"] = end
-	}
-	return params
-}
-
-// executeFeedGroupListAllPages fetches all pages and merges items/deleted_items
-// into a single response, then enriches the merged result.
-func executeFeedGroupListAllPages(rt *common.RuntimeContext) error {
-	maxPages := rt.Int("page-limit")
-	if maxPages < 1 {
-		maxPages = 20
-	}
-	if maxPages > 1000 {
-		maxPages = 1000
-	}
-
-	// Use make([]any, 0) so empty arrays serialize as [] not null.
-	allItems := make([]any, 0)
-	allDeletedItems := make([]any, 0)
-	var lastHasMore bool
-	var lastPageToken string
-	prevPageToken := "__START__"
-
-	for page := 0; page < maxPages; page++ {
-		params := larkcore.QueryParams{
-			"page_size": []string{strconv.Itoa(rt.Int("page-size"))},
-		}
-		if page > 0 {
-			params["page_token"] = []string{lastPageToken}
-		}
-		if start := rt.Str("start-time"); start != "" {
-			params["start_time"] = []string{start}
-		}
-		if end := rt.Str("end-time"); end != "" {
-			params["end_time"] = []string{end}
-		}
-
-		data, err := rt.DoAPIJSONTyped("GET", feedGroupListItemPath(rt), params, nil)
-		if err != nil {
-			return err
-		}
-
-		if v, ok := data["items"].([]any); ok {
-			allItems = append(allItems, v...)
-		}
-		if v, ok := data["deleted_items"].([]any); ok {
-			allDeletedItems = append(allDeletedItems, v...)
-		}
-
-		lastHasMore, _ = data["has_more"].(bool)
-		lastPageToken, _ = data["page_token"].(string)
-
-		fmt.Fprintf(rt.IO().ErrOut, "page %d: %d items, %d deleted\n",
-			page+1, len(allItems), len(allDeletedItems))
-
-		if !lastHasMore || lastPageToken == "" {
-			break
-		}
-		if lastPageToken == prevPageToken {
-			fmt.Fprintf(rt.IO().ErrOut, "warning: page_token did not change, stopping pagination to avoid infinite loop\n")
-			break
-		}
-		prevPageToken = lastPageToken
-	}
-
-	merged := map[string]any{
-		"items":         allItems,
-		"deleted_items": allDeletedItems,
-		"has_more":      lastHasMore,
-		"page_token":    lastPageToken,
-	}
-
-	enrichFeedGroupItemsChatName(rt, merged)
-
-	rt.OutFormat(merged, nil, func(w io.Writer) {
-		renderFeedGroupItemsTable(w, merged, lastHasMore)
-	})
-	return nil
-}

shortcuts/im/im_feed_group_list_test.go

@@ -1,257 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package im
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"strings"
-	"testing"
-)
-
-func fgGroup(id string) map[string]interface{} {
-	return map[string]interface{}{"group_id": id, "name": id, "type": "normal"}
-}
-
-// TestFeedGroupListPageAllMergesBothLists is the core regression for the
-// +feed-group-list shortcut: a dual-list response (groups + deleted_groups) must
-// have BOTH lists merged across pages — including active groups that appear only
-// on a later page. This is what the raw `feed.groups list --page-all` gets wrong.
-func TestFeedGroupListPageAllMergesBothLists(t *testing.T) {
-	var reqs []recordedFGRequest
-	runtime := newFGRuntime(t, ImFeedGroupList, map[string]string{"page-all": "true", "page-size": "5"}, &reqs,
-		func(_ string, page int) (int, interface{}) {
-			if page == 1 {
-				// page 1 fills up with mostly deleted groups; the active groups
-				// g1/g2 here plus one more (g3) on page 2.
-				return 200, wrapData(map[string]interface{}{
-					"groups":         []interface{}{fgGroup("g1"), fgGroup("g2")},
-					"deleted_groups": []interface{}{fgGroup("d1"), fgGroup("d2"), fgGroup("d3")},
-					"page_token":     "TKN", "has_more": true,
-				})
-			}
-			return 200, wrapData(map[string]interface{}{
-				"groups":         []interface{}{fgGroup("g3")},
-				"deleted_groups": []interface{}{fgGroup("d4")},
-				"page_token":     "", "has_more": false,
-			})
-		})
-
-	if err := ImFeedGroupList.Execute(context.Background(), runtime); err != nil {
-		t.Fatalf("Execute: %v", err)
-	}
-
-	if got := countFGRequests(reqs, "/groups"); got != 2 {
-		t.Fatalf("expected 2 groups requests, got %d", got)
-	}
-	if got := firstQueryValue(reqs[1].query, "page_token"); got != "TKN" {
-		t.Errorf("second page token = %q, want TKN", got)
-	}
-
-	out, _ := runtime.Factory.IOStreams.Out.(*bytes.Buffer)
-	if out == nil {
-		t.Fatal("stdout buffer missing")
-	}
-	var parsed map[string]interface{}
-	if err := json.Unmarshal(out.Bytes(), &parsed); err != nil {
-		t.Fatalf("output not JSON: %v\n%s", err, out.String())
-	}
-	data, _ := parsed["data"].(map[string]interface{})
-	if got := len(data["groups"].([]interface{})); got != 3 {
-		t.Errorf("merged groups = %d, want 3 (active list must include later pages)", got)
-	}
-	if got := len(data["deleted_groups"].([]interface{})); got != 4 {
-		t.Errorf("merged deleted_groups = %d, want 4 (secondary list must also merge)", got)
-	}
-}
-
-// TestFeedGroupListAlwaysSendsPageToken locks the fix for the groups endpoint's
-// requirement that page_token be present even on the first page (HTTP 400
-// "Missing required parameter: page_token" otherwise).
-func TestFeedGroupListAlwaysSendsPageToken(t *testing.T) {
-	var reqs []recordedFGRequest
-	runtime := newFGRuntime(t, ImFeedGroupList, map[string]string{"page-size": "10"}, &reqs,
-		func(_ string, _ int) (int, interface{}) {
-			return 200, wrapData(map[string]interface{}{
-				"groups": []interface{}{}, "deleted_groups": []interface{}{},
-				"page_token": "", "has_more": false,
-			})
-		})
-
-	if err := ImFeedGroupList.Execute(context.Background(), runtime); err != nil {
-		t.Fatalf("Execute: %v", err)
-	}
-	req := findFGRequest(reqs, "/groups")
-	if req == nil {
-		t.Fatal("no /groups request recorded")
-	}
-	if _, ok := req.query["page_token"]; !ok {
-		t.Errorf("first request must carry page_token query param (empty = first page); query=%v", req.query)
-	}
-}
-
-// TestFeedGroupListValidation checks flag validation surfaces clear errors.
-func TestFeedGroupListValidation(t *testing.T) {
-	cases := []struct {
-		name  string
-		flags map[string]string
-		want  string
-	}{
-		{"page-size too small", map[string]string{"page-size": "0"}, "--page-size"},
-		{"page-size too large", map[string]string{"page-size": "51"}, "--page-size"},
-		{"page-limit too large", map[string]string{"page-limit": "1001"}, "--page-limit"},
-		{"bad start-time", map[string]string{"start-time": "notnum"}, "--start-time"},
-		{"bad end-time", map[string]string{"end-time": "notnum"}, "--end-time"},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			runtime := newFGRuntime(t, ImFeedGroupList, tc.flags, nil, nil)
-			err := ImFeedGroupList.Validate(context.Background(), runtime)
-			if err == nil {
-				t.Fatalf("expected validation error containing %q, got nil", tc.want)
-			}
-			if !bytes.Contains([]byte(err.Error()), []byte(tc.want)) {
-				t.Errorf("error = %q, want substring %q", err.Error(), tc.want)
-			}
-		})
-	}
-}
-
-// TestFeedGroupListSinglePageTableOutput covers the non-page-all Execute path:
-// time-window params must reach the query, and the pretty table must render
-// group_id / name / type with the summary, pagination hint and deleted count.
-func TestFeedGroupListSinglePageTableOutput(t *testing.T) {
-	var reqs []recordedFGRequest
-	runtime := newFGRuntime(t, ImFeedGroupList, map[string]string{
-		"start-time": "100", "end-time": "200",
-	}, &reqs, func(_ string, _ int) (int, interface{}) {
-		return 200, wrapData(map[string]interface{}{
-			"groups":         []interface{}{fgGroup("g1"), fgGroup("g2")},
-			"deleted_groups": []interface{}{fgGroup("d1")},
-			"page_token":     "TKN", "has_more": true,
-		})
-	})
-	runtime.Format = "pretty"
-
-	if err := ImFeedGroupList.Execute(context.Background(), runtime); err != nil {
-		t.Fatalf("Execute: %v", err)
-	}
-	if got := countFGRequests(reqs, "/groups"); got != 1 {
-		t.Fatalf("expected 1 groups request, got %d", got)
-	}
-	if got := firstQueryValue(reqs[0].query, "start_time"); got != "100" {
-		t.Errorf("start_time query = %q, want 100", got)
-	}
-	if got := firstQueryValue(reqs[0].query, "end_time"); got != "200" {
-		t.Errorf("end_time query = %q, want 200", got)
-	}
-
-	out, _ := runtime.Factory.IOStreams.Out.(*bytes.Buffer)
-	if out == nil {
-		t.Fatal("stdout buffer missing")
-	}
-	got := out.String()
-	for _, want := range []string{"group_id", "g1", "g2", "2 group(s)", "more available", "(1 deleted)"} {
-		if !strings.Contains(got, want) {
-			t.Errorf("table output missing %q; got:\n%s", want, got)
-		}
-	}
-}
-
-// TestFeedGroupListDryRun locks the dry-run shape: GET /groups with page_size,
-// page_token (always present) and the optional time-window params.
-func TestFeedGroupListDryRun(t *testing.T) {
-	runtime := newFGRuntime(t, ImFeedGroupList, map[string]string{
-		"page-size": "10", "page-token": "TKN", "start-time": "100", "end-time": "200",
-	}, nil, nil)
-	d := ImFeedGroupList.DryRun(context.Background(), runtime)
-	calls := dryRunCalls(t, d)
-	if len(calls) != 1 {
-		t.Fatalf("expected 1 call, got %d", len(calls))
-	}
-	if calls[0]["method"] != "GET" {
-		t.Errorf("method = %v, want GET", calls[0]["method"])
-	}
-	if url, _ := calls[0]["url"].(string); !strings.HasSuffix(url, "/open-apis/im/v1/groups") {
-		t.Errorf("url = %s", url)
-	}
-	params, _ := calls[0]["params"].(map[string]interface{})
-	for key, want := range map[string]string{
-		"page_size": "10", "page_token": "TKN", "start_time": "100", "end_time": "200",
-	} {
-		if params[key] != want {
-			t.Errorf("params %s = %v, want %s", key, params[key], want)
-		}
-	}
-}
-
-func TestFeedGroupListDryRunValidationError(t *testing.T) {
-	runtime := newFGRuntime(t, ImFeedGroupList, map[string]string{"page-size": "0"}, nil, nil)
-	d := ImFeedGroupList.DryRun(context.Background(), runtime)
-	m := dryRunJSON(t, d)
-	errMsg, _ := m["error"].(string)
-	if !strings.Contains(errMsg, "--page-size") {
-		t.Errorf("dry-run error = %q, want --page-size validation message", errMsg)
-	}
-}
-
-// TestFeedGroupListPageAllStopsOnRepeatedToken locks the infinite-loop guard:
-// when the server keeps returning the same page_token with has_more=true,
-// pagination must stop after the repeat and warn on stderr. Also exercises the
-// defensive page-limit clamping (Execute is called directly, bypassing Validate).
-func TestFeedGroupListPageAllStopsOnRepeatedToken(t *testing.T) {
-	for _, tc := range []struct {
-		name      string
-		pageLimit string
-	}{
-		{"limit clamped up from 0", "0"},
-		{"limit clamped down from 1001", "1001"},
-	} {
-		t.Run(tc.name, func(t *testing.T) {
-			var reqs []recordedFGRequest
-			runtime := newFGRuntime(t, ImFeedGroupList, map[string]string{
-				"page-all": "true", "page-limit": tc.pageLimit, "start-time": "100", "end-time": "200",
-			}, &reqs, func(_ string, _ int) (int, interface{}) {
-				return 200, wrapData(map[string]interface{}{
-					"groups":         []interface{}{fgGroup("g1")},
-					"deleted_groups": []interface{}{},
-					"page_token":     "SAME", "has_more": true,
-				})
-			})
-			runtime.Format = "pretty" // exercise the page-all table-render path too
-			if err := ImFeedGroupList.Execute(context.Background(), runtime); err != nil {
-				t.Fatalf("Execute: %v", err)
-			}
-			if got := countFGRequests(reqs, "/groups"); got != 2 {
-				t.Errorf("expected 2 requests (stop on repeated token), got %d", got)
-			}
-			errOut, _ := runtime.Factory.IOStreams.ErrOut.(*bytes.Buffer)
-			if !strings.Contains(errOut.String(), "page_token did not change") {
-				t.Errorf("stderr missing loop warning; got:\n%s", errOut.String())
-			}
-		})
-	}
-}
-
-// TestFeedGroupListAPIError checks both Execute paths surface API errors.
-func TestFeedGroupListAPIError(t *testing.T) {
-	for _, tc := range []struct {
-		name  string
-		flags map[string]string
-	}{
-		{"single page", map[string]string{}},
-		{"page-all", map[string]string{"page-all": "true"}},
-	} {
-		t.Run(tc.name, func(t *testing.T) {
-			runtime := newFGRuntime(t, ImFeedGroupList, tc.flags, nil,
-				func(_ string, _ int) (int, interface{}) {
-					return 200, map[string]interface{}{"code": 99999, "msg": "boom"}
-				})
-			if err := ImFeedGroupList.Execute(context.Background(), runtime); err == nil {
-				t.Fatal("expected API error, got nil")
-			}
-		})
-	}
-}

shortcuts/im/im_feed_group_query_item.go

@@ -1,90 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package im
-
-import (
-	"context"
-	"io"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-// ImFeedGroupQueryItem provides the +feed-group-query-item shortcut: it looks up
-// specific feed cards in a feed group by ID and enriches each item with chat_name
-// resolved from its feed_id.
-var ImFeedGroupQueryItem = common.Shortcut{
-	Service:     "im",
-	Command:     "+feed-group-query-item",
-	Description: "Look up specific feed cards in a feed group (tag) by ID; user-only; enriches each item with chat_name resolved from feed_id",
-	Risk:        "read",
-	UserScopes:  []string{feedGroupReadScope, chatReadScope},
-	AuthTypes:   []string{"user"},
-	HasFormat:   true,
-	Flags: []common.Flag{
-		{Name: "feed-group-id", Desc: "feed group ID (ofg_xxx); path parameter (required)"},
-		{Name: "feed-id", Desc: "comma-separated chat IDs (oc_xxx); feed_type is fixed to chat (required)"},
-	},
-	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		_, err := buildFeedGroupQueryItemBody(runtime)
-		return err
-	},
-	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		body, err := buildFeedGroupQueryItemBody(runtime)
-		if err != nil {
-			return common.NewDryRunAPI().Set("error", err.Error())
-		}
-		return common.NewDryRunAPI().
-			POST(feedGroupQueryItemPath(runtime)).
-			Body(body).
-			Desc("will also POST /open-apis/im/v1/chats/batch_query to resolve chat_name from feed_id; requires im:chat:read")
-	},
-	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		body, err := buildFeedGroupQueryItemBody(runtime)
-		if err != nil {
-			return err
-		}
-
-		data, err := runtime.DoAPIJSONTyped("POST", feedGroupQueryItemPath(runtime), nil, body)
-		if err != nil {
-			return err
-		}
-		enrichFeedGroupItemsChatName(runtime, data)
-
-		runtime.OutFormat(data, nil, func(w io.Writer) {
-			renderFeedGroupItemsTable(w, data, false)
-		})
-		return nil
-	},
-}
-
-// feedGroupQueryItemPath builds the batch_query_item endpoint path with the
-// feed_group_id segment safely encoded.
-func feedGroupQueryItemPath(rt *common.RuntimeContext) string {
-	return "/open-apis/im/v1/groups/" + validate.EncodePathSegment(rt.Str("feed-group-id")) + "/batch_query_item"
-}
-
-// buildFeedGroupQueryItemBody validates the flags and constructs the request body
-// {"items":[{"feed_id":"<tok>","feed_type":"chat"}, ...]}.
-func buildFeedGroupQueryItemBody(rt *common.RuntimeContext) (map[string]any, error) {
-	if rt.Str("feed-group-id") == "" {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--feed-group-id is required").WithParam("--feed-group-id")
-	}
-	tokens := common.SplitCSV(rt.Str("feed-id"))
-	items := make([]any, 0, len(tokens))
-	for _, tok := range tokens {
-		if tok == "" {
-			continue
-		}
-		items = append(items, map[string]any{
-			"feed_id":   tok,
-			"feed_type": "chat",
-		})
-	}
-	if len(items) == 0 {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--feed-id is required (comma-separated chat IDs)").WithParam("--feed-id")
-	}
-	return map[string]any{"items": items}, nil
-}

shortcuts/im/im_flag_cancel.go

@@ -15,13 +15,14 @@ import (
 // ImFlagCancel provides the +flag-cancel shortcut for removing a bookmark.
 // When no --flag-type is given, it performs double-cancel: removes both message and feed layers.
 var ImFlagCancel = common.Shortcut{
-	Service:     "im",
-	Command:     "+flag-cancel",
-	Description: "Cancel (remove) a bookmark. When no --flag-type is given, best-effort double-cancel: removes message layer and (when chat_type is determinable) feed layer",
-	Risk:        "write",
-	UserScopes:  flagWriteLookupScopes,
-	AuthTypes:   []string{"user"},
-	HasFormat:   true,
+	Service: "im",
+	Command: "+flag-cancel",
+	Description: "Cancel (remove) a bookmark. When no --flag-type is given, " +
+		"performs double-cancel: removes both message and feed layers",
+	Risk:       "write",
+	UserScopes: flagWriteLookupScopes,
+	AuthTypes:  []string{"user"},
+	HasFormat:  true,
 	Flags: []common.Flag{
 		{Name: "message-id", Desc: "message ID (om_xxx)"},
 		{Name: "item-type", Desc: "item type override: default|thread|msg_thread"},

shortcuts/im/im_flag_create.go

@@ -16,7 +16,7 @@ import (
 var ImFlagCreate = common.Shortcut{
 	Service:     "im",
 	Command:     "+flag-create",
-	Description: "Create a bookmark on a message; user-only; defaults to message-layer flag; use --flag-type feed for feed-layer flag (item_type auto-detected from chat mode)",
+	Description: "Create a bookmark on a message; user-only; defaults to message-layer flag; use --flag-type feed to create feed-layer flag (auto-detects chat type)",
 	Risk:        "write",
 	UserScopes:  flagWriteLookupScopes,
 	AuthTypes:   []string{"user"},

shortcuts/im/shortcuts.go

@@ -25,8 +25,5 @@ func Shortcuts() []common.Shortcut {
 		ImFeedShortcutCreate,
 		ImFeedShortcutRemove,
 		ImFeedShortcutList,
-		ImFeedGroupList,
-		ImFeedGroupListItem,
-		ImFeedGroupQueryItem,
 	}
 }

shortcuts/minutes/minutes_download.go

@@ -17,7 +17,6 @@ import (
 	"strings"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
@@ -55,29 +54,29 @@ var MinutesDownload = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		tokens := common.SplitCSV(runtime.Str("minute-tokens"))
 		if len(tokens) == 0 {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-tokens is required").WithParam("--minute-tokens")
+			return output.ErrValidation("--minute-tokens is required")
 		}
 		if len(tokens) > maxBatchSize {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-tokens: too many tokens (%d), maximum is %d", len(tokens), maxBatchSize).WithParam("--minute-tokens")
+			return output.ErrValidation("--minute-tokens: too many tokens (%d), maximum is %d", len(tokens), maxBatchSize)
 		}
 		for _, token := range tokens {
 			if !validMinuteToken.MatchString(token) {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid minute token %q: must contain only lowercase alphanumeric characters (e.g. obcnq3b9jl72l83w4f149w9c)", token).WithParam("--minute-tokens")
+				return output.ErrValidation("invalid minute token %q: must contain only lowercase alphanumeric characters (e.g. obcnq3b9jl72l83w4f149w9c)", token)
 			}
 		}
 		// Cheap checks first, then path-safety resolution.
 		out := runtime.Str("output")
 		outDir := runtime.Str("output-dir")
 		if out != "" && outDir != "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output and --output-dir cannot both be set").WithParam("--output")
+			return output.ErrValidation("--output and --output-dir cannot both be set")
 		}
 		if out != "" {
-			if err := common.ValidateSafePathTyped(runtime.FileIO(), out); err != nil {
+			if err := common.ValidateSafePath(runtime.FileIO(), out); err != nil {
 				return err
 			}
 		}
 		if outDir != "" {
-			if err := common.ValidateSafePathTyped(runtime.FileIO(), outDir); err != nil {
+			if err := common.ValidateSafePath(runtime.FileIO(), outDir); err != nil {
 				return err
 			}
 		}
@@ -113,7 +112,7 @@ var MinutesDownload = common.Shortcut{
 				explicitOutputPath = ""
 			case statErr == nil && !fi.IsDir():
 				if !single {
-					return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output %q is a file; batch mode expects a directory (use --output-dir)", explicitOutputPath).WithParam("--output")
+					return output.ErrValidation("--output %q is a file; batch mode expects a directory (use --output-dir)", explicitOutputPath)
 				}
 			case errors.Is(statErr, fs.ErrNotExist):
 				if !single {
@@ -121,7 +120,7 @@ var MinutesDownload = common.Shortcut{
 					explicitOutputPath = ""
 				}
 			default:
-				return errs.NewInternalError(errs.SubtypeFileIO, "cannot access --output %q: %s", explicitOutputPath, statErr).WithCause(statErr)
+				return output.Errorf(output.ExitAPI, "io_error", "cannot access --output %q: %s", explicitOutputPath, statErr)
 			}
 		}
 
@@ -138,7 +137,6 @@ var MinutesDownload = common.Shortcut{
 			SizeBytes    int64  `json:"size_bytes,omitempty"`
 			DownloadURL  string `json:"download_url,omitempty"`
 			Error        string `json:"error,omitempty"`
-			err          error  // raw typed error for single-mode passthrough
 		}
 
 		results := make([]result, len(tokens))
@@ -153,18 +151,18 @@ var MinutesDownload = common.Shortcut{
 		// download URLs originate from the trusted Lark API, not user input.
 		baseClient, err := runtime.Factory.HttpClient()
 		if err != nil {
-			return errs.NewNetworkError(errs.SubtypeNetworkTransport, "failed to get HTTP client: %s", err).WithCause(err)
+			return output.ErrNetwork("failed to get HTTP client: %s", err)
 		}
 		clonedClient := *baseClient
 		clonedClient.Timeout = disableClientTimeout
 		clonedClient.CheckRedirect = func(req *http.Request, via []*http.Request) error {
 			if len(via) >= maxDownloadRedirects {
-				return fmt.Errorf("too many redirects") //nolint:forbidigo // returned to net/http CheckRedirect, not a CLI terminal error
+				return fmt.Errorf("too many redirects")
 			}
 			if len(via) > 0 {
 				prev := via[len(via)-1]
 				if strings.EqualFold(prev.URL.Scheme, "https") && strings.EqualFold(req.URL.Scheme, "http") {
-					return fmt.Errorf("redirect from https to http is not allowed") //nolint:forbidigo // returned to net/http CheckRedirect, not a CLI terminal error
+					return fmt.Errorf("redirect from https to http is not allowed")
 				}
 			}
 			return validate.ValidateDownloadSourceURL(req.Context(), req.URL.String())
@@ -195,7 +193,7 @@ var MinutesDownload = common.Shortcut{
 
 			downloadURL, err := fetchDownloadURL(ctx, runtime, token)
 			if err != nil {
-				results[i] = result{MinuteToken: token, Error: err.Error(), err: err}
+				results[i] = result{MinuteToken: token, Error: err.Error()}
 				continue
 			}
 
@@ -222,7 +220,7 @@ var MinutesDownload = common.Shortcut{
 
 			dl, err := downloadMediaFile(ctx, dlClient, downloadURL, token, opts)
 			if err != nil {
-				results[i] = result{MinuteToken: token, Error: err.Error(), err: err}
+				results[i] = result{MinuteToken: token, Error: err.Error()}
 				continue
 			}
 			results[i] = result{
@@ -237,10 +235,7 @@ var MinutesDownload = common.Shortcut{
 		if single {
 			r := results[0]
 			if r.Error != "" {
-				if r.err != nil {
-					return r.err // typed error from fetchDownloadURL/downloadMediaFile, exit code preserved
-				}
-				return runtime.OutPartialFailure(map[string]interface{}{"downloads": results}, &output.Meta{Count: len(results)})
+				return output.ErrAPI(0, r.Error, nil)
 			}
 			if urlOnly {
 				runtime.Out(map[string]interface{}{
@@ -267,19 +262,17 @@ var MinutesDownload = common.Shortcut{
 		}
 		fmt.Fprintf(errOut, "[minutes +download] done: %d total, %d succeeded, %d failed\n", len(results), successCount, len(results)-successCount)
 
-		outData := map[string]interface{}{"downloads": results}
-		meta := &output.Meta{Count: len(results)}
+		runtime.OutFormat(map[string]interface{}{"downloads": results}, &output.Meta{Count: len(results)}, nil)
 		if successCount == 0 && len(results) > 0 {
-			return runtime.OutPartialFailure(outData, meta)
+			return output.ErrAPI(0, fmt.Sprintf("all %d downloads failed", len(results)), nil)
 		}
-		runtime.OutFormat(outData, meta, nil)
 		return nil
 	},
 }
 
 // fetchDownloadURL retrieves the pre-signed download URL for a minute token.
 func fetchDownloadURL(ctx context.Context, runtime *common.RuntimeContext, minuteToken string) (string, error) {
-	data, err := runtime.CallAPITyped(http.MethodGet,
+	data, err := runtime.DoAPIJSON(http.MethodGet,
 		fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/media", validate.EncodePathSegment(minuteToken)),
 		nil, nil)
 	if err != nil {
@@ -287,7 +280,7 @@ func fetchDownloadURL(ctx context.Context, runtime *common.RuntimeContext, minut
 	}
 	downloadURL := common.GetString(data, "download_url")
 	if downloadURL == "" {
-		return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "API returned empty download_url for %s", minuteToken)
+		return "", output.Errorf(output.ExitAPI, "api_error", "API returned empty download_url for %s", minuteToken)
 	}
 	return downloadURL, nil
 }
@@ -309,26 +302,26 @@ type downloadOpts struct {
 // Filename resolution: opts.outputPath > Content-Disposition filename > Content-Type ext > <token>.media.
 func downloadMediaFile(ctx context.Context, client *http.Client, downloadURL, minuteToken string, opts downloadOpts) (*downloadResult, error) {
 	if err := validate.ValidateDownloadSourceURL(ctx, downloadURL); err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "blocked download URL: %s", err).WithCause(err)
+		return nil, output.ErrValidation("blocked download URL: %s", err)
 	}
 
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, downloadURL, nil)
 	if err != nil {
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "invalid download URL: %s", err).WithCause(err)
+		return nil, output.ErrNetwork("invalid download URL: %s", err)
 	}
 
 	resp, err := client.Do(req)
 	if err != nil {
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "download failed: %s", err).WithCause(err)
+		return nil, output.ErrNetwork("download failed: %s", err)
 	}
 	defer resp.Body.Close()
 
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
 		body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
 		if len(body) > 0 {
-			return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "download failed: HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+			return nil, output.ErrNetwork("download failed: HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
 		}
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "download failed: HTTP %d", resp.StatusCode)
+		return nil, output.ErrNetwork("download failed: HTTP %d", resp.StatusCode)
 	}
 
 	// resolve output path
@@ -347,7 +340,7 @@ func downloadMediaFile(ctx context.Context, client *http.Client, downloadURL, mi
 
 	if !opts.overwrite {
 		if _, statErr := opts.fio.Stat(outputPath); statErr == nil {
-			return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "output file already exists: %s (use --overwrite to replace)", outputPath)
+			return nil, output.ErrValidation("output file already exists: %s (use --overwrite to replace)", outputPath)
 		}
 	}
 
@@ -356,7 +349,7 @@ func downloadMediaFile(ctx context.Context, client *http.Client, downloadURL, mi
 		ContentLength: resp.ContentLength,
 	}, resp.Body)
 	if err != nil {
-		return nil, common.WrapSaveErrorTyped(err)
+		return nil, common.WrapSaveErrorByCategory(err, "io")
 	}
 	resolvedPath, err := opts.fio.ResolvePath(outputPath)
 	if err != nil || resolvedPath == "" {

shortcuts/minutes/minutes_download_test.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"errors"
 	"net/http"
 	"os"
 	"strings"
@@ -16,11 +15,9 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -697,284 +694,3 @@ func TestDownload_Batch_DryRun(t *testing.T) {
 		t.Errorf("dry-run should show tokens, got: %s", out)
 	}
 }
-
-// ---------------------------------------------------------------------------
-// Typed-error lock tests
-// ---------------------------------------------------------------------------
-
-// TestDownload_TypedErr_ValidationInvalidArgument verifies that an invalid
-// minute token format (passing cobra's required check but failing our regex)
-// returns a *errs.ValidationError with SubtypeInvalidArgument and the expected
-// Param.  This locks site :64 (invalid minute token %q).
-func TestDownload_TypedErr_ValidationInvalidArgument(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
-	err := mountAndRun(t, MinutesDownload, []string{
-		"+download", "--minute-tokens", "INVALID***TOKEN", "--as", "user",
-	}, f, nil)
-	if err == nil {
-		t.Fatal("expected error, got nil")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "--minute-tokens" {
-		t.Errorf("Param = %q, want %q", ve.Param, "--minute-tokens")
-	}
-}
-
-// TestDownload_TypedErr_NetworkTransport_HttpError verifies that a non-2xx
-// download response from downloadMediaFile returns a *errs.NetworkError with
-// SubtypeNetworkTransport.
-//
-// In the end-to-end single-token Execute path the typed error is now passed
-// through directly via r.err (single-mode passthrough).  We call downloadMediaFile
-// directly via a probe shortcut to assert the typed shape at the source.
-func TestDownload_TypedErr_NetworkTransport_HttpError(t *testing.T) {
-	chdir(t, t.TempDir())
-
-	var capturedErr error
-	probe := common.Shortcut{
-		Service:   "minutes",
-		Command:   "+probe-dl",
-		AuthTypes: []string{"bot"},
-		Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-			client, err := rctx.Factory.HttpClient()
-			if err != nil {
-				return err
-			}
-			_, capturedErr = downloadMediaFile(ctx, client,
-				"https://example.com/presigned/download", "tok001",
-				downloadOpts{fio: rctx.FileIO(), outputPath: "out.mp4"})
-			return nil
-		},
-	}
-
-	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	reg.Register(&httpmock.Stub{
-		URL:     "example.com/presigned/download",
-		Status:  503,
-		RawBody: []byte("Service Unavailable"),
-	})
-
-	if err := mountAndRun(t, probe, []string{"+probe-dl", "--as", "bot"}, f, nil); err != nil {
-		t.Fatalf("probe shortcut should not error: %v", err)
-	}
-	if capturedErr == nil {
-		t.Fatal("expected downloadMediaFile to return an error for HTTP 503, got nil")
-	}
-	var ne *errs.NetworkError
-	if !errors.As(capturedErr, &ne) {
-		t.Fatalf("expected *errs.NetworkError, got %T: %v", capturedErr, capturedErr)
-	}
-	if ne.Subtype != errs.SubtypeNetworkTransport {
-		t.Errorf("Subtype = %q, want %q", ne.Subtype, errs.SubtypeNetworkTransport)
-	}
-	if !strings.Contains(ne.Error(), "503") {
-		t.Errorf("error message should contain status code 503, got: %v", ne)
-	}
-}
-
-// TestDownload_TypedErr_InternalInvalidResponse verifies that fetchDownloadURL
-// returns *errs.InternalError with SubtypeInvalidResponse when the API
-// response contains an empty download_url field.
-//
-// In the end-to-end single-token Execute path the typed error is now passed
-// through directly via r.err (single-mode passthrough).  The typed assertion
-// is also made at the fetchDownloadURL call site directly via a probe shortcut.
-func TestDownload_TypedErr_InternalInvalidResponse(t *testing.T) {
-	var capturedErr error
-	probe := common.Shortcut{
-		Service:   "minutes",
-		Command:   "+probe-download-url",
-		AuthTypes: []string{"bot"},
-		Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-			_, capturedErr = fetchDownloadURL(ctx, rctx, "tok001")
-			// Always return nil so mountAndRun doesn't swallow the error type.
-			return nil
-		},
-	}
-
-	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/minutes/v1/minutes/tok001/media",
-		Status: 200,
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{"download_url": ""},
-		},
-	})
-
-	if err := mountAndRun(t, probe, []string{"+probe-download-url", "--as", "bot"}, f, nil); err != nil {
-		t.Fatalf("probe shortcut should not error: %v", err)
-	}
-	if capturedErr == nil {
-		t.Fatal("expected fetchDownloadURL to return an error for empty download_url, got nil")
-	}
-	var ie *errs.InternalError
-	if !errors.As(capturedErr, &ie) {
-		t.Fatalf("expected *errs.InternalError, got %T: %v", capturedErr, capturedErr)
-	}
-	if ie.Subtype != errs.SubtypeInvalidResponse {
-		t.Errorf("Subtype = %q, want %q", ie.Subtype, errs.SubtypeInvalidResponse)
-	}
-	if !strings.Contains(ie.Error(), "download_url") {
-		t.Errorf("error message should mention download_url, got: %v", ie)
-	}
-}
-
-// TestDownload_TypedErr_OverwriteProtection verifies that the overwrite guard
-// in downloadMediaFile returns *errs.ValidationError with SubtypeFailedPrecondition.
-//
-// In the end-to-end single-token Execute path this typed error is now passed
-// through directly via r.err (single-mode passthrough), so the typed shape is
-// also asserted end-to-end via the probe shortcut.
-func TestDownload_TypedErr_OverwriteProtection(t *testing.T) {
-	chdir(t, t.TempDir())
-	if err := os.WriteFile("existing.mp4", []byte("old"), 0644); err != nil {
-		t.Fatalf("setup failed: %v", err)
-	}
-
-	var capturedErr error
-	probe := common.Shortcut{
-		Service:   "minutes",
-		Command:   "+probe-overwrite",
-		AuthTypes: []string{"bot"},
-		Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
-			client, err := rctx.Factory.HttpClient()
-			if err != nil {
-				return err
-			}
-			_, capturedErr = downloadMediaFile(ctx, client,
-				"https://example.com/presigned/download", "tok001",
-				downloadOpts{fio: rctx.FileIO(), outputPath: "existing.mp4", overwrite: false})
-			return nil
-		},
-	}
-
-	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	reg.Register(downloadStub("example.com/presigned/download", []byte("new-content"), "video/mp4"))
-
-	if err := mountAndRun(t, probe, []string{"+probe-overwrite", "--as", "bot"}, f, nil); err != nil {
-		t.Fatalf("probe shortcut should not error: %v", err)
-	}
-	if capturedErr == nil {
-		t.Fatal("expected downloadMediaFile to return an error for existing file without overwrite, got nil")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(capturedErr, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", capturedErr, capturedErr)
-	}
-	if ve.Subtype != errs.SubtypeFailedPrecondition {
-		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeFailedPrecondition)
-	}
-	if !strings.Contains(ve.Error(), "exists") {
-		t.Errorf("error message should mention exists, got: %v", ve)
-	}
-}
-
-// TestDownload_TypedErr_SingleMode_PassthroughTyped verifies that in single-token
-// mode a typed error from fetchDownloadURL or downloadMediaFile is returned
-// directly to the caller with its Problem shape intact (exit code preserved).
-func TestDownload_TypedErr_SingleMode_PassthroughTyped(t *testing.T) {
-	chdir(t, t.TempDir())
-
-	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	// API returns non-zero code → CallAPITyped yields a typed APIError.
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/minutes/v1/minutes/tok001/media",
-		Status: 200,
-		Body: map[string]interface{}{
-			"code": 99991, "msg": "permission denied",
-			"data": map[string]interface{}{},
-		},
-	})
-
-	err := mountAndRun(t, MinutesDownload, []string{
-		"+download", "--minute-tokens", "tok001", "--output", "out.mp4", "--as", "bot",
-	}, f, nil)
-	if err == nil {
-		t.Fatal("expected error for API failure, got nil")
-	}
-
-	// The error must carry a Problem (typed envelope).
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected typed error (ProblemOf ok), got %T: %v", err, err)
-	}
-	if p == nil {
-		t.Fatal("ProblemOf returned nil Problem")
-	}
-
-	// Exit code must be non-zero and come from the typed error, not a generic 1.
-	code := output.ExitCodeOf(err)
-	if code == 0 {
-		t.Errorf("ExitCodeOf typed error = 0, want non-zero")
-	}
-}
-
-// TestDownload_TypedErr_Batch_AllFail_OutPartialFailure verifies that when every
-// token in a batch fails, Execute emits an ok:false stdout envelope (carrying the
-// full downloads array) and returns *output.PartialFailureError with Code==ExitAPI.
-// This locks the double-emit fix: the old code called OutFormat then returned ErrAPI;
-// the new code calls OutPartialFailure once.
-func TestDownload_TypedErr_Batch_AllFail_OutPartialFailure(t *testing.T) {
-	chdir(t, t.TempDir())
-
-	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	// Both tokens fail at the API level.
-	for _, tok := range []string{"tok001", "tok002"} {
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/minutes/v1/minutes/" + tok + "/media",
-			Status: 200,
-			Body: map[string]interface{}{
-				"code": 99991, "msg": "permission denied",
-				"data": map[string]interface{}{},
-			},
-		})
-	}
-
-	err := mountAndRun(t, MinutesDownload, []string{
-		"+download", "--minute-tokens", "tok001,tok002", "--as", "bot",
-	}, f, stdout)
-
-	// Must return *output.PartialFailureError with ExitAPI.
-	var pfErr *output.PartialFailureError
-	if !errors.As(err, &pfErr) {
-		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
-	}
-	if pfErr.Code != output.ExitAPI {
-		t.Errorf("PartialFailureError.Code = %d, want %d (ExitAPI)", pfErr.Code, output.ExitAPI)
-	}
-
-	// stdout must carry ok:false with the downloads array (both failed entries).
-	var env struct {
-		OK   bool `json:"ok"`
-		Data struct {
-			Downloads []struct {
-				MinuteToken string `json:"minute_token"`
-				Error       string `json:"error"`
-			} `json:"downloads"`
-		} `json:"data"`
-	}
-	if jsonErr := json.Unmarshal(stdout.Bytes(), &env); jsonErr != nil {
-		t.Fatalf("failed to parse stdout: %v\nraw: %s", jsonErr, stdout.String())
-	}
-	if env.OK {
-		t.Errorf("ok must be false on all-fail batch, got ok:true\nstdout: %s", stdout.String())
-	}
-	if len(env.Data.Downloads) != 2 {
-		t.Fatalf("expected 2 download entries, got %d\nstdout: %s", len(env.Data.Downloads), stdout.String())
-	}
-	for _, d := range env.Data.Downloads {
-		if d.Error == "" {
-			t.Errorf("token %s: expected non-empty error field in all-fail batch", d.MinuteToken)
-		}
-	}
-}

shortcuts/minutes/minutes_search.go

@@ -13,7 +13,6 @@ import (
 	"time"
 	"unicode/utf8"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -36,28 +35,28 @@ func parseTimeRange(runtime *common.RuntimeContext) (string, string, error) {
 	if start != "" {
 		parsed, err := toRFC3339(start)
 		if err != nil {
-			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start: %v", err).WithParam("--start")
+			return "", "", output.ErrValidation("--start: %v", err)
 		}
 		startTime = parsed
 	}
 	if end != "" {
 		parsed, err := toRFC3339(end, "end")
 		if err != nil {
-			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
+			return "", "", output.ErrValidation("--end: %v", err)
 		}
 		endTime = parsed
 	}
 	if startTime != "" && endTime != "" {
 		st, err := time.Parse(time.RFC3339, startTime)
 		if err != nil {
-			return "", "", errs.NewInternalError(errs.SubtypeUnknown, "parse normalized --start: %v", err).WithCause(err)
+			return "", "", fmt.Errorf("parse normalized --start: %w", err)
 		}
 		et, err := time.Parse(time.RFC3339, endTime)
 		if err != nil {
-			return "", "", errs.NewInternalError(errs.SubtypeUnknown, "parse normalized --end: %v", err).WithCause(err)
+			return "", "", fmt.Errorf("parse normalized --end: %w", err)
 		}
 		if st.After(et) {
-			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start (%s) is after --end (%s)", start, end).WithParam("--start")
+			return "", "", output.ErrValidation("--start (%s) is after --end (%s)", start, end)
 		}
 	}
 	return startTime, endTime, nil
@@ -71,7 +70,7 @@ func toRFC3339(input string, hint ...string) (string, error) {
 	}
 	sec, err := strconv.ParseInt(ts, 10, 64)
 	if err != nil {
-		return "", fmt.Errorf("invalid timestamp %q: %w", ts, err) //nolint:forbidigo // intermediate parse error; callers wrap it into a typed ValidationError
+		return "", fmt.Errorf("invalid timestamp %q: %w", ts, err)
 	}
 	return time.Unix(sec, 0).Format(time.RFC3339), nil
 }
@@ -95,7 +94,7 @@ func buildTimeFilter(startTime, endTime string) map[string]interface{} {
 func buildMinutesSearchFilter(runtime *common.RuntimeContext, startTime, endTime string) (map[string]interface{}, error) {
 	filter := map[string]interface{}{}
 
-	ownerIDs, err := common.ResolveOpenIDsTyped("--owner-ids", common.SplitCSV(runtime.Str("owner-ids")), runtime)
+	ownerIDs, err := common.ResolveOpenIDs("--owner-ids", common.SplitCSV(runtime.Str("owner-ids")), runtime)
 	if err != nil {
 		return nil, err
 	}
@@ -103,7 +102,7 @@ func buildMinutesSearchFilter(runtime *common.RuntimeContext, startTime, endTime
 		filter["owner_ids"] = ownerIDs
 	}
 
-	participantIDs, err := common.ResolveOpenIDsTyped("--participant-ids", common.SplitCSV(runtime.Str("participant-ids")), runtime)
+	participantIDs, err := common.ResolveOpenIDs("--participant-ids", common.SplitCSV(runtime.Str("participant-ids")), runtime)
 	if err != nil {
 		return nil, err
 	}
@@ -232,26 +231,26 @@ var MinutesSearch = common.Shortcut{
 			return err
 		}
 		if q := strings.TrimSpace(runtime.Str("query")); q != "" && utf8.RuneCountInString(q) > maxMinutesSearchQueryLen {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--query: length must be between 1 and 50 characters").WithParam("--query")
+			return output.ErrValidation("--query: length must be between 1 and 50 characters")
 		}
-		if _, err := common.ValidatePageSizeTyped(runtime, "page-size", defaultMinutesSearchPageSize, 1, maxMinutesSearchPageSize); err != nil {
+		if _, err := common.ValidatePageSize(runtime, "page-size", defaultMinutesSearchPageSize, 1, maxMinutesSearchPageSize); err != nil {
 			return err
 		}
-		ownerIDs, err := common.ResolveOpenIDsTyped("--owner-ids", common.SplitCSV(runtime.Str("owner-ids")), runtime)
+		ownerIDs, err := common.ResolveOpenIDs("--owner-ids", common.SplitCSV(runtime.Str("owner-ids")), runtime)
 		if err != nil {
 			return err
 		}
 		for _, id := range ownerIDs {
-			if _, err := common.ValidateUserIDTyped("--owner-ids", id); err != nil {
+			if _, err := common.ValidateUserID(id); err != nil {
 				return err
 			}
 		}
-		participantIDs, err := common.ResolveOpenIDsTyped("--participant-ids", common.SplitCSV(runtime.Str("participant-ids")), runtime)
+		participantIDs, err := common.ResolveOpenIDs("--participant-ids", common.SplitCSV(runtime.Str("participant-ids")), runtime)
 		if err != nil {
 			return err
 		}
 		for _, id := range participantIDs {
-			if _, err := common.ValidateUserIDTyped("--participant-ids", id); err != nil {
+			if _, err := common.ValidateUserID(id); err != nil {
 				return err
 			}
 		}
@@ -260,7 +259,7 @@ var MinutesSearch = common.Shortcut{
 				return nil
 			}
 		}
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify at least one of --query, --owner-ids, --participant-ids, --start, or --end")
+		return common.FlagErrorf("specify at least one of --query, --owner-ids, --participant-ids, --start, or --end")
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		startTime, endTime, err := parseTimeRange(runtime)
@@ -289,7 +288,7 @@ var MinutesSearch = common.Shortcut{
 			return err
 		}
 
-		data, err := runtime.CallAPITyped(http.MethodPost, "/open-apis/minutes/v1/minutes/search", buildMinutesSearchParams(runtime), body)
+		data, err := runtime.CallAPI(http.MethodPost, "/open-apis/minutes/v1/minutes/search", buildMinutesSearchParams(runtime), body)
 		if err != nil {
 			return err
 		}

shortcuts/minutes/minutes_search_test.go

@@ -6,11 +6,9 @@ package minutes
 import (
 	"context"
 	"encoding/json"
-	"errors"
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -65,11 +63,10 @@ func TestMinutesSearchParseTimeRangeErrors(t *testing.T) {
 		start       string
 		end         string
 		wantMessage string
-		wantParam   string
 	}{
-		{name: "invalid start", start: "bad-start", wantMessage: "--start:", wantParam: "--start"},
-		{name: "invalid end", end: "bad-end", wantMessage: "--end:", wantParam: "--end"},
-		{name: "start after end", start: "2026-03-26", end: "2026-03-25", wantMessage: "is after --end", wantParam: "--start"},
+		{name: "invalid start", start: "bad-start", wantMessage: "--start:"},
+		{name: "invalid end", end: "bad-end", wantMessage: "--end:"},
+		{name: "start after end", start: "2026-03-26", end: "2026-03-25", wantMessage: "is after --end"},
 	}
 
 	for _, tt := range tests {
@@ -91,16 +88,6 @@ func TestMinutesSearchParseTimeRangeErrors(t *testing.T) {
 			if !strings.Contains(err.Error(), tt.wantMessage) {
 				t.Fatalf("error = %v, want %q", err, tt.wantMessage)
 			}
-			var ve *errs.ValidationError
-			if !errors.As(err, &ve) {
-				t.Fatalf("expected *errs.ValidationError, got %T", err)
-			}
-			if ve.Subtype != errs.SubtypeInvalidArgument {
-				t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-			}
-			if ve.Param != tt.wantParam {
-				t.Fatalf("Param = %q, want %q", ve.Param, tt.wantParam)
-			}
 		})
 	}
 }
@@ -222,16 +209,6 @@ func TestMinutesSearchValidationMeRequiresResolvableUser(t *testing.T) {
 			if !strings.Contains(err.Error(), "resolvable open_id") {
 				t.Fatalf("unexpected error: %v", err)
 			}
-			var ve *errs.ValidationError
-			if !errors.As(err, &ve) {
-				t.Fatalf("expected *errs.ValidationError, got %T", err)
-			}
-			if ve.Subtype != errs.SubtypeInvalidArgument {
-				t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-			}
-			if ve.Param != "--"+tt.flag {
-				t.Fatalf("Param = %q, want --%s", ve.Param, tt.flag)
-			}
 		})
 	}
 }
@@ -290,13 +267,6 @@ func TestMinutesSearchValidationNoFilter(t *testing.T) {
 	if !strings.Contains(err.Error(), "specify at least one") {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T", err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-	}
 }
 
 // TestMinutesSearchValidationInvalidParticipantID verifies participant IDs must be valid open_ids.
@@ -309,16 +279,6 @@ func TestMinutesSearchValidationInvalidParticipantID(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected invalid user ID error")
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T", err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-	}
-	if ve.Param != "--participant-ids" {
-		t.Fatalf("Param = %q, want --participant-ids", ve.Param)
-	}
 }
 
 // TestMinutesSearchValidationInvalidOwnerID verifies owner IDs must be valid open_ids.
@@ -331,16 +291,6 @@ func TestMinutesSearchValidationInvalidOwnerID(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected invalid owner ID error")
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T", err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-	}
-	if ve.Param != "--owner-ids" {
-		t.Fatalf("Param = %q, want --owner-ids", ve.Param)
-	}
 }
 
 // TestMinutesSearchValidationQueryTooLong verifies overly long queries are rejected.
@@ -356,16 +306,6 @@ func TestMinutesSearchValidationQueryTooLong(t *testing.T) {
 	if !strings.Contains(err.Error(), "length must be between 1 and 50 characters") {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T", err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-	}
-	if ve.Param != "--query" {
-		t.Fatalf("Param = %q, want --query", ve.Param)
-	}
 }
 
 // TestMinutesSearchValidationMaxPageSize30 verifies the maximum allowed page size passes validation.
@@ -395,16 +335,6 @@ func TestMinutesSearchValidationPageSizeAboveMax(t *testing.T) {
 	if !strings.Contains(err.Error(), "--page-size") {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T", err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-	}
-	if ve.Param != "--page-size" {
-		t.Fatalf("Param = %q, want --page-size", ve.Param)
-	}
 }
 
 // TestMinutesSearchValidationTimeErrors verifies time parsing failures surface through validation.
@@ -442,13 +372,6 @@ func TestMinutesSearchValidationTimeErrors(t *testing.T) {
 			if !strings.Contains(err.Error(), tt.wantMessage) {
 				t.Fatalf("error = %v, want %q", err, tt.wantMessage)
 			}
-			var ve *errs.ValidationError
-			if !errors.As(err, &ve) {
-				t.Fatalf("expected *errs.ValidationError, got %T", err)
-			}
-			if ve.Subtype != errs.SubtypeInvalidArgument {
-				t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-			}
 		})
 	}
 }

shortcuts/minutes/minutes_speaker_replace.go

@@ -5,11 +5,12 @@ package minutes
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"net/http"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -36,27 +37,27 @@ var MinutesSpeakerReplace = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
 		if minuteToken == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-token is required").WithParam("--minute-token")
+			return output.ErrValidation("--minute-token is required")
 		}
 		if err := validate.ResourceName(minuteToken, "--minute-token"); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--minute-token")
+			return output.ErrValidation("%s", err)
 		}
 		fromUserID := strings.TrimSpace(runtime.Str("from-user-id"))
 		if fromUserID == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--from-user-id is required").WithParam("--from-user-id")
+			return output.ErrValidation("--from-user-id is required")
 		}
-		if _, err := common.ValidateUserIDTyped("--from-user-id", fromUserID); err != nil {
-			return err
+		if _, err := common.ValidateUserID(fromUserID); err != nil {
+			return output.ErrValidation("--from-user-id: %s", err)
 		}
 		toUserID := strings.TrimSpace(runtime.Str("to-user-id"))
 		if toUserID == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--to-user-id is required").WithParam("--to-user-id")
+			return output.ErrValidation("--to-user-id is required")
 		}
-		if _, err := common.ValidateUserIDTyped("--to-user-id", toUserID); err != nil {
-			return err
+		if _, err := common.ValidateUserID(toUserID); err != nil {
+			return output.ErrValidation("--to-user-id: %s", err)
 		}
 		if fromUserID == toUserID {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--from-user-id and --to-user-id must be different").WithParam("--to-user-id")
+			return output.ErrValidation("--from-user-id and --to-user-id must be different")
 		}
 		return nil
 	},
@@ -83,7 +84,7 @@ var MinutesSpeakerReplace = common.Shortcut{
 			"to_user_id":   toUserID,
 		}
 
-		_, err := runtime.CallAPITyped(http.MethodPut,
+		_, err := runtime.CallAPI(http.MethodPut,
 			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken)),
 			nil, body)
 		if err != nil {
@@ -102,18 +103,37 @@ var MinutesSpeakerReplace = common.Shortcut{
 }
 
 func minutesSpeakerReplaceError(err error, minuteToken, fromUserID string) error {
-	p, ok := errs.ProblemOf(err)
-	if !ok {
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil {
 		return err
 	}
-	switch p.Code {
+
+	switch exitErr.Detail.Code {
 	case minutesSpeakerReplaceNoEditPermission:
-		p.Message = fmt.Sprintf("No edit permission for minute %q: cannot replace the transcript speaker.", minuteToken)
-		p.Hint = "Ask the minute owner for minute edit permission"
+		return &output.ExitError{
+			Code: output.ExitAPI,
+			Detail: &output.ErrDetail{
+				Type:    "no_edit_permission",
+				Code:    minutesSpeakerReplaceNoEditPermission,
+				Message: fmt.Sprintf("No edit permission for minute %q: cannot replace the transcript speaker.", minuteToken),
+				Hint:    "Ask the minute owner for minute edit permission",
+				Detail:  exitErr.Detail.Detail,
+			},
+			Err: err,
+		}
 	case minutesSpeakerReplaceSpeakerNotFoundCode:
-		p.Subtype = errs.SubtypeNotFound
-		p.Message = fmt.Sprintf("Speaker not found in minute %q: --from-user-id %q does not match an existing speaker in the transcript.", minuteToken, fromUserID)
-		p.Hint = "Check --minute-token and --from-user-id. Use an open_id for a speaker that appears in the minute transcript, then retry."
+		return &output.ExitError{
+			Code: output.ExitAPI,
+			Detail: &output.ErrDetail{
+				Type:    "speaker_not_found",
+				Code:    minutesSpeakerReplaceSpeakerNotFoundCode,
+				Message: fmt.Sprintf("Speaker not found in minute %q: --from-user-id %q does not match an existing speaker in the transcript.", minuteToken, fromUserID),
+				Hint:    "Check --minute-token and --from-user-id. Use an open_id for a speaker that appears in the minute transcript, then retry.",
+				Detail:  exitErr.Detail.Detail,
+			},
+			Err: err,
+		}
 	}
+
 	return err
 }

shortcuts/minutes/minutes_speaker_replace_test.go

@@ -10,9 +10,9 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )
 
@@ -44,12 +44,12 @@ func TestMinutesSpeakerReplace_Validate(t *testing.T) {
 		{
 			name:    "invalid from prefix",
 			args:    []string{"+speaker-replace", "--minute-token", "obcn123456", "--from-user-id", "u_a", "--to-user-id", "ou_b", "--as", "user"},
-			wantErr: "invalid user ID format",
+			wantErr: "--from-user-id",
 		},
 		{
 			name:    "invalid to prefix",
 			args:    []string{"+speaker-replace", "--minute-token", "obcn123456", "--from-user-id", "ou_a", "--to-user-id", "u_b", "--as", "user"},
-			wantErr: "invalid user ID format",
+			wantErr: "--to-user-id",
 		},
 		{
 			name:    "from equals to",
@@ -76,52 +76,6 @@ func TestMinutesSpeakerReplace_Validate(t *testing.T) {
 	}
 }
 
-func TestMinutesSpeakerReplace_ValidateTyped(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
-
-	tests := []struct {
-		name      string
-		args      []string
-		wantParam string
-	}{
-		{
-			name:      "invalid from prefix",
-			args:      []string{"+speaker-replace", "--minute-token", "obcn123456", "--from-user-id", "u_a", "--to-user-id", "ou_b", "--as", "user"},
-			wantParam: "--from-user-id",
-		},
-		{
-			name:      "from equals to",
-			args:      []string{"+speaker-replace", "--minute-token", "obcn123456", "--from-user-id", "ou_same", "--to-user-id", "ou_same", "--as", "user"},
-			wantParam: "--to-user-id",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			parent := &cobra.Command{Use: "minutes"}
-			MinutesSpeakerReplace.Mount(parent, f)
-			parent.SetArgs(tt.args)
-			parent.SilenceErrors = true
-			parent.SilenceUsage = true
-			err := parent.Execute()
-			if err == nil {
-				t.Fatalf("expected error, got nil")
-			}
-			var ve *errs.ValidationError
-			if !errors.As(err, &ve) {
-				t.Fatalf("want *errs.ValidationError, got %T", err)
-			}
-			if ve.Subtype != errs.SubtypeInvalidArgument {
-				t.Errorf("subtype=%q", ve.Subtype)
-			}
-			if ve.Param != tt.wantParam {
-				t.Errorf("param=%q, want %q", ve.Param, tt.wantParam)
-			}
-		})
-	}
-}
-
 func TestMinutesSpeakerReplace_DryRun(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
@@ -225,21 +179,24 @@ func TestMinutesSpeakerReplace_SpeakerNotFound(t *testing.T) {
 		t.Fatal("expected speaker-not-found error, got nil")
 	}
 
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("want typed errs.*, got %T: %v", err, err)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
 	}
-	if p.Subtype != errs.SubtypeNotFound {
-		t.Errorf("subtype = %q, want %q", p.Subtype, errs.SubtypeNotFound)
+	if exitErr.Detail == nil {
+		t.Fatalf("expected structured error detail, got nil")
 	}
-	if !strings.Contains(p.Message, "Speaker not found") {
-		t.Errorf("message should be friendly, got: %s", p.Message)
+	if exitErr.Detail.Type != "speaker_not_found" {
+		t.Errorf("error type = %q, want speaker_not_found", exitErr.Detail.Type)
 	}
-	if !strings.Contains(p.Message, "ou_missing_speaker") {
-		t.Errorf("message should include missing speaker id, got: %s", p.Message)
+	if !strings.Contains(exitErr.Detail.Message, "Speaker not found") {
+		t.Errorf("message should be friendly, got: %s", exitErr.Detail.Message)
 	}
-	if !strings.Contains(p.Hint, "--from-user-id") {
-		t.Errorf("hint should mention --from-user-id, got: %s", p.Hint)
+	if !strings.Contains(exitErr.Detail.Message, "ou_missing_speaker") {
+		t.Errorf("message should include missing speaker id, got: %s", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "--from-user-id") {
+		t.Errorf("hint should mention --from-user-id, got: %s", exitErr.Detail.Hint)
 	}
 }
 
@@ -268,20 +225,23 @@ func TestMinutesSpeakerReplace_NoEditPermission(t *testing.T) {
 		t.Fatal("expected no-edit-permission error, got nil")
 	}
 
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("want typed errs.*, got %T: %v", err, err)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
 	}
-	if p.Subtype != errs.SubtypePermissionDenied {
-		t.Errorf("subtype = %q, want %q", p.Subtype, errs.SubtypePermissionDenied)
+	if exitErr.Detail == nil {
+		t.Fatalf("expected structured error detail, got nil")
 	}
-	if !strings.Contains(p.Message, "No edit permission") {
-		t.Errorf("message should be friendly, got: %s", p.Message)
+	if exitErr.Detail.Type != "no_edit_permission" {
+		t.Errorf("error type = %q, want no_edit_permission", exitErr.Detail.Type)
 	}
-	if !strings.Contains(p.Message, minutesSpeakerReplaceTestToken) {
-		t.Errorf("message should include minute token, got: %s", p.Message)
+	if !strings.Contains(exitErr.Detail.Message, "No edit permission") {
+		t.Errorf("message should be friendly, got: %s", exitErr.Detail.Message)
 	}
-	if !strings.Contains(p.Hint, "edit permission") {
-		t.Errorf("hint should mention edit permission, got: %s", p.Hint)
+	if !strings.Contains(exitErr.Detail.Message, minutesSpeakerReplaceTestToken) {
+		t.Errorf("message should include minute token, got: %s", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "edit permission") {
+		t.Errorf("hint should mention edit permission, got: %s", exitErr.Detail.Hint)
 	}
 }

shortcuts/minutes/minutes_update.go

@@ -5,11 +5,12 @@ package minutes
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"net/http"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -32,13 +33,13 @@ var MinutesUpdate = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
 		if minuteToken == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-token is required").WithParam("--minute-token")
+			return output.ErrValidation("--minute-token is required")
 		}
 		if err := validate.ResourceName(minuteToken, "--minute-token"); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--minute-token")
+			return output.ErrValidation("%s", err)
 		}
 		if strings.TrimSpace(runtime.Str("topic")) == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--topic is required").WithParam("--topic")
+			return output.ErrValidation("--topic is required")
 		}
 		return nil
 	},
@@ -56,7 +57,7 @@ var MinutesUpdate = common.Shortcut{
 			"topic": topic,
 		}
 
-		_, err := runtime.CallAPITyped(http.MethodPatch,
+		_, err := runtime.CallAPI(http.MethodPatch,
 			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)),
 			nil, body)
 		if err != nil {
@@ -74,11 +75,20 @@ var MinutesUpdate = common.Shortcut{
 }
 
 func minutesUpdateError(err error, minuteToken string) error {
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Code != minutesUpdateNoEditPermissionCode {
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil || exitErr.Detail.Code != minutesUpdateNoEditPermissionCode {
 		return err
 	}
-	p.Message = fmt.Sprintf("No edit permission for minute %q: cannot update the title.", minuteToken)
-	p.Hint = "Ask the minute owner for minute edit permission"
-	return err
+
+	return &output.ExitError{
+		Code: output.ExitAPI,
+		Detail: &output.ErrDetail{
+			Type:    "no_edit_permission",
+			Code:    minutesUpdateNoEditPermissionCode,
+			Message: fmt.Sprintf("No edit permission for minute %q: cannot update the title.", minuteToken),
+			Hint:    "Ask the minute owner for minute edit permission",
+			Detail:  exitErr.Detail.Detail,
+		},
+		Err: err,
+	}
 }

shortcuts/minutes/minutes_update_test.go

@@ -9,9 +9,9 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/spf13/cobra"
 )
 
@@ -55,32 +55,6 @@ func TestMinutesUpdate_Validate(t *testing.T) {
 	}
 }
 
-func TestMinutesUpdate_ValidateTyped(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
-
-	// ".." triggers ResourceName rejection — hits our Validate, not cobra's required-flag check.
-	parent := &cobra.Command{Use: "minutes"}
-	MinutesUpdate.Mount(parent, f)
-	parent.SetArgs([]string{"+update", "--minute-token", "..", "--topic", "title", "--as", "user"})
-	parent.SilenceErrors = true
-	parent.SilenceUsage = true
-	err := parent.Execute()
-	if err == nil {
-		t.Fatalf("expected error, got nil")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("want *errs.ValidationError, got %T", err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("subtype=%q", ve.Subtype)
-	}
-	if ve.Param != "--minute-token" {
-		t.Errorf("param=%q", ve.Param)
-	}
-}
-
 func TestMinutesUpdate_DryRun(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
@@ -158,20 +132,23 @@ func TestMinutesUpdate_NoEditPermission(t *testing.T) {
 		t.Fatal("expected no-edit-permission error, got nil")
 	}
 
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("want typed errs.*, got %T: %v", err, err)
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) {
+		t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
 	}
-	if p.Subtype != errs.SubtypePermissionDenied {
-		t.Errorf("subtype = %q, want %q", p.Subtype, errs.SubtypePermissionDenied)
+	if exitErr.Detail == nil {
+		t.Fatalf("expected structured error detail, got nil")
 	}
-	if !strings.Contains(p.Message, "No edit permission") {
-		t.Errorf("message should be friendly, got: %s", p.Message)
+	if exitErr.Detail.Type != "no_edit_permission" {
+		t.Errorf("error type = %q, want no_edit_permission", exitErr.Detail.Type)
 	}
-	if !strings.Contains(p.Message, minutesUpdateTestToken) {
-		t.Errorf("message should include minute token, got: %s", p.Message)
+	if !strings.Contains(exitErr.Detail.Message, "No edit permission") {
+		t.Errorf("message should be friendly, got: %s", exitErr.Detail.Message)
 	}
-	if !strings.Contains(p.Hint, "edit permission") {
-		t.Errorf("hint should mention edit permission, got: %s", p.Hint)
+	if !strings.Contains(exitErr.Detail.Message, minutesUpdateTestToken) {
+		t.Errorf("message should include minute token, got: %s", exitErr.Detail.Message)
+	}
+	if !strings.Contains(exitErr.Detail.Hint, "edit permission") {
+		t.Errorf("hint should mention edit permission, got: %s", exitErr.Detail.Hint)
 	}
 }

shortcuts/minutes/minutes_upload.go

@@ -6,7 +6,7 @@ package minutes
 import (
 	"context"
 
-	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -36,10 +36,10 @@ var MinutesUpload = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		fileToken := runtime.Str("file-token")
 		if fileToken == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--file-token is required").WithParam("--file-token")
+			return output.ErrValidation("--file-token is required")
 		}
 		if err := validate.ResourceName(fileToken, "--file-token"); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--file-token")
+			return output.ErrValidation("%s", err)
 		}
 		return nil
 	},
@@ -55,7 +55,7 @@ var MinutesUpload = common.Shortcut{
 			"file_token": fileToken,
 		}
 
-		data, err := runtime.CallAPITyped("POST", "/open-apis/minutes/v1/minutes/upload", nil, body)
+		data, err := runtime.CallAPI("POST", "/open-apis/minutes/v1/minutes/upload", nil, body)
 		if err != nil {
 			return err
 		}

shortcuts/minutes/minutes_upload_test.go

@@ -5,12 +5,10 @@ package minutes
 
 import (
 	"encoding/json"
-	"errors"
 	"net/http"
 	"strings"
 	"testing"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/spf13/cobra"
@@ -48,31 +46,6 @@ func TestMinutesUpload_Validate(t *testing.T) {
 	}
 }
 
-func TestMinutesUpload_ValidateTyped(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
-
-	// ".." triggers ResourceName rejection — hits our Validate, not cobra's required-flag check.
-	parent := &cobra.Command{Use: "minutes"}
-	MinutesUpload.Mount(parent, f)
-	parent.SetArgs([]string{"+upload", "--file-token", "..", "--as", "user"})
-	parent.SilenceErrors = true
-	parent.SilenceUsage = true
-	err := parent.Execute()
-	if err == nil {
-		t.Fatalf("expected error, got nil")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("want *errs.ValidationError, got %T", err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("subtype=%q", ve.Subtype)
-	}
-	if ve.Param != "--file-token" {
-		t.Errorf("param=%q", ve.Param)
-	}
-}
-
 func TestMinutesUpload_HelpMetadata(t *testing.T) {
 	if len(MinutesUpload.Flags) == 0 {
 		t.Fatal("expected file-token flag metadata")

shortcuts/register_test.go

@@ -155,7 +155,7 @@ func TestRegisterShortcutsMountsDocsMediaPreview(t *testing.T) {
 	}
 }
 
-func TestRegisterShortcutsDocsHelpAddsSkillReadGuidance(t *testing.T) {
+func TestRegisterShortcutsDocsHelpAddsVersionSelectorAndUpgradeTips(t *testing.T) {
 	program := &cobra.Command{Use: "root"}
 	RegisterShortcuts(program, newRegisterTestFactory(t))
 
@@ -166,111 +166,121 @@ func TestRegisterShortcutsDocsHelpAddsSkillReadGuidance(t *testing.T) {
 	if docsCmd == nil || docsCmd.Name() != "docs" {
 		t.Fatalf("docs command not mounted: %#v", docsCmd)
 	}
-	if docsCmd.Flags().Lookup("api-version") != nil {
-		t.Fatal("docs command should not expose service-level --api-version")
+	if docsCmd.Flags().Lookup("api-version") == nil {
+		t.Fatal("docs command should expose --api-version for versioned help")
 	}
 
 	if !strings.Contains(docsCmd.Long, "Document and content operations.") {
 		t.Fatalf("docs long help missing default description:\n%s", docsCmd.Long)
 	}
 
-	for _, child := range docsCmd.Commands() {
-		if child.Name() == "+get-skill" {
-			t.Fatal("docs +get-skill should not be mounted")
-		}
-	}
-
 	var defaultHelp bytes.Buffer
 	docsCmd.SetOut(&defaultHelp)
 	if err := docsCmd.Help(); err != nil {
 		t.Fatalf("docs help failed: %v", err)
 	}
 	for _, want := range []string{
-		"Start here (required for AI agents):",
-		"lark-cli skills read lark-doc",
-		"AI agents MUST read the matching embedded skill",
-		"Do not skip this step",
-		"MUST NOT grep/open local SKILL.md files",
+		"Tips:",
+		"Docs v1 is deprecated and will be removed soon",
+		"Check the installed lark-doc skill first",
+		"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
+		"After confirming lark-doc is v2",
+		"use `--api-version v2` with docs +create, docs +fetch, and docs +update",
 	} {
 		if !strings.Contains(defaultHelp.String(), want) {
 			t.Fatalf("docs default help missing %q:\n%s", want, defaultHelp.String())
 		}
 	}
-	if startIdx, usageIdx := strings.Index(defaultHelp.String(), "Start here (required for AI agents):"), strings.Index(defaultHelp.String(), "Usage:"); startIdx < 0 || usageIdx < 0 || startIdx > usageIdx {
-		t.Fatalf("docs help should show Start here before Usage:\n%s", defaultHelp.String())
+}
+
+func TestRegisterShortcutsDocsV2HelpUsesV2Description(t *testing.T) {
+	program := &cobra.Command{Use: "root"}
+	RegisterShortcuts(program, newRegisterTestFactory(t))
+
+	docsCmd, _, err := program.Find([]string{"docs"})
+	if err != nil {
+		t.Fatalf("find docs command: %v", err)
+	}
+	if err := docsCmd.Flags().Set("api-version", "v2"); err != nil {
+		t.Fatalf("set docs api-version: %v", err)
+	}
+
+	var out bytes.Buffer
+	docsCmd.SetOut(&out)
+	if err := docsCmd.Help(); err != nil {
+		t.Fatalf("docs v2 help failed: %v", err)
+	}
+
+	for _, want := range []string{
+		"Document and content operations (v2).",
+		"Tips:",
+		"Check the installed lark-doc skill first",
+		"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
+	} {
+		if !strings.Contains(out.String(), want) {
+			t.Fatalf("docs v2 help missing %q:\n%s", want, out.String())
+		}
 	}
 	for _, unwanted := range []string{
-		"Tips:",
-		"+get-skill",
-		"Docs shortcuts are v2-only",
 		"Docs v1 is deprecated and will be removed soon",
-		"lark-cli update",
-		"upgrade skills",
-		"Use --api-version v2 for the latest API",
+		"After confirming lark-doc is v2",
+		"use `--api-version v2` with docs +create, docs +fetch, and docs +update",
 	} {
-		if strings.Contains(defaultHelp.String(), unwanted) {
-			t.Fatalf("docs help should not include %q:\n%s", unwanted, defaultHelp.String())
+		if strings.Contains(out.String(), unwanted) {
+			t.Fatalf("docs v2 help should not include %q:\n%s", unwanted, out.String())
 		}
 	}
 }
 
-func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
+func TestRegisterShortcutsDocsVersionedShortcutHelpAddsVersionTips(t *testing.T) {
 	tests := []struct {
-		name         string
-		shortcut     string
-		shortcutHelp string
-		visibleFlag  string
-		skillCommand string
-		hiddenFlags  []string
-		contentHelp  []string
-		unwanted     []string
+		name          string
+		shortcut      string
+		apiVersion    string
+		shortcutHelp  string
+		versionedFlag string
 	}{
 		{
-			name:         "create",
-			shortcut:     "+create",
-			shortcutHelp: "Create a Lark document",
-			visibleFlag:  "--content",
-			skillCommand: "lark-cli skills read lark-doc references/lark-doc-create.md",
-			hiddenFlags:  []string{"title", "markdown", "folder-token", "wiki-node", "wiki-space"},
-			contentHelp: []string{
-				"AI agents MUST read",
-				"lark-cli skills read lark-doc references/lark-doc-xml.md",
-				"before writing any --content payload",
-				"when using --doc-format markdown, also read",
-				"lark-cli skills read lark-doc references/lark-doc-md.md",
-				"Follow the latest rules",
-				"MUST NOT grep/open local SKILL.md files",
-				"use --help for the latest command flags",
-			},
-			unwanted: []string{"--markdown", "--title", "--folder-token", "--wiki-node", "--wiki-space"},
+			name:          "create v1",
+			shortcut:      "+create",
+			apiVersion:    "v1",
+			shortcutHelp:  "Create a Lark document",
+			versionedFlag: "--markdown",
 		},
 		{
-			name:         "fetch",
-			shortcut:     "+fetch",
-			shortcutHelp: "Fetch Lark document content",
-			visibleFlag:  "read scope",
-			skillCommand: "lark-cli skills read lark-doc references/lark-doc-fetch.md",
-			hiddenFlags:  []string{"offset", "limit"},
-			unwanted:     []string{"--offset", "--limit"},
+			name:          "create v2",
+			shortcut:      "+create",
+			apiVersion:    "v2",
+			shortcutHelp:  "Create a Lark document",
+			versionedFlag: "--content",
 		},
 		{
-			name:         "update",
-			shortcut:     "+update",
-			shortcutHelp: "Update a Lark document",
-			visibleFlag:  "--command",
-			skillCommand: "lark-cli skills read lark-doc references/lark-doc-update.md",
-			hiddenFlags:  []string{"mode", "markdown", "selection-with-ellipsis", "selection-by-title", "new-title"},
-			contentHelp: []string{
-				"AI agents MUST read",
-				"lark-cli skills read lark-doc references/lark-doc-xml.md",
-				"before writing any --content payload",
-				"when using --doc-format markdown, also read",
-				"lark-cli skills read lark-doc references/lark-doc-md.md",
-				"Follow the latest rules",
-				"MUST NOT grep/open local SKILL.md files",
-				"use --help for the latest command flags",
-			},
-			unwanted: []string{"--mode", "--markdown", "--selection-with-ellipsis", "--selection-by-title", "--new-title"},
+			name:          "fetch v1",
+			shortcut:      "+fetch",
+			apiVersion:    "v1",
+			shortcutHelp:  "Fetch Lark document content",
+			versionedFlag: "--offset",
+		},
+		{
+			name:          "fetch v2",
+			shortcut:      "+fetch",
+			apiVersion:    "v2",
+			shortcutHelp:  "Fetch Lark document content",
+			versionedFlag: "partial read scope",
+		},
+		{
+			name:          "update v1",
+			shortcut:      "+update",
+			apiVersion:    "v1",
+			shortcutHelp:  "Update a Lark document",
+			versionedFlag: "--mode",
+		},
+		{
+			name:          "update v2",
+			shortcut:      "+update",
+			apiVersion:    "v2",
+			shortcutHelp:  "Update a Lark document",
+			versionedFlag: "--command",
 		},
 	}
 
@@ -286,25 +296,8 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
 			if cmd == nil || cmd.Name() != tt.shortcut {
 				t.Fatalf("docs %s shortcut not mounted: %#v", tt.shortcut, cmd)
 			}
-
-			for _, flagName := range tt.hiddenFlags {
-				flag := cmd.Flags().Lookup(flagName)
-				if flag == nil {
-					t.Fatalf("docs %s missing hidden compatibility flag %q", tt.shortcut, flagName)
-				}
-				if !flag.Hidden {
-					t.Fatalf("docs %s flag %q should be hidden", tt.shortcut, flagName)
-				}
-			}
-			apiVersionFlag := cmd.Flags().Lookup("api-version")
-			if apiVersionFlag == nil {
-				t.Fatalf("docs %s missing --api-version flag", tt.shortcut)
-			}
-			if apiVersionFlag.Hidden {
-				t.Fatalf("docs %s --api-version should be visible", tt.shortcut)
-			}
-			if apiVersionFlag.DefValue != "v2" {
-				t.Fatalf("docs %s --api-version default = %q, want v2", tt.shortcut, apiVersionFlag.DefValue)
+			if err := cmd.Flags().Set("api-version", tt.apiVersion); err != nil {
+				t.Fatalf("set docs %s api-version: %v", tt.shortcut, err)
 			}
 
 			var out bytes.Buffer
@@ -313,39 +306,49 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
 				t.Fatalf("docs %s help failed: %v", tt.shortcut, err)
 			}
 
+			wantTips := []string{
+				"Tips:",
+				"Docs v1 is deprecated and will be removed soon",
+				"Check the installed lark-doc skill first",
+				"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
+				"After confirming lark-doc is v2",
+				"use `--api-version v2` with docs +create, docs +fetch, and docs +update",
+			}
+			unwantedTips := []string{
+				"[NOTE]",
+				"Use --api-version v2 for the latest API",
+				"otherwise use the default v1 flags",
+				"legacy v1 examples and flags",
+			}
+			if tt.apiVersion == "v2" {
+				wantTips = []string{
+					"Tips:",
+					"Check the installed lark-doc skill first",
+					"if it is not the v2 skill, run `lark-cli update` to upgrade skills",
+				}
+				unwantedTips = append(unwantedTips,
+					"Docs v1 is deprecated and will be removed soon",
+					"After confirming lark-doc is v2",
+					"use `--api-version v2` with docs +create, docs +fetch, and docs +update",
+				)
+			}
+
 			for _, want := range []string{
 				tt.shortcutHelp,
-				tt.visibleFlag,
-				"--api-version",
-				"deprecated compatibility flag; docs shortcuts always use v2",
-				"both v1/v2 are accepted",
-				"(default \"v2\")",
-				"Start here (required for AI agents):",
-				"AI agents MUST read the matching embedded skill",
-				"Do not skip this step",
-				"MUST NOT grep/open local SKILL.md files",
-				tt.skillCommand,
+				tt.versionedFlag,
 			} {
 				if !strings.Contains(out.String(), want) {
-					t.Fatalf("docs %s help missing %q:\n%s", tt.shortcut, want, out.String())
+					t.Fatalf("docs %s %s help missing %q:\n%s", tt.shortcut, tt.apiVersion, want, out.String())
 				}
 			}
-			for _, want := range tt.contentHelp {
+			for _, want := range wantTips {
 				if !strings.Contains(out.String(), want) {
-					t.Fatalf("docs %s content help missing %q:\n%s", tt.shortcut, want, out.String())
+					t.Fatalf("docs %s %s help missing %q:\n%s", tt.shortcut, tt.apiVersion, want, out.String())
 				}
 			}
-			if startIdx, usageIdx := strings.Index(out.String(), "Start here (required for AI agents):"), strings.Index(out.String(), "Usage:"); startIdx < 0 || usageIdx < 0 || startIdx > usageIdx {
-				t.Fatalf("docs %s help should show Start here before Usage:\n%s", tt.shortcut, out.String())
-			}
-			for _, unwanted := range []string{"Tips:", "+get-skill", "Docs shortcuts are v2-only"} {
+			for _, unwanted := range unwantedTips {
 				if strings.Contains(out.String(), unwanted) {
-					t.Fatalf("docs %s help should not include %q:\n%s", tt.shortcut, unwanted, out.String())
-				}
-			}
-			for _, unwanted := range tt.unwanted {
-				if strings.Contains(out.String(), unwanted) {
-					t.Fatalf("docs %s help should not include %q:\n%s", tt.shortcut, unwanted, out.String())
+					t.Fatalf("docs %s %s help should not include %q:\n%s", tt.shortcut, tt.apiVersion, unwanted, out.String())
 				}
 			}
 		})

shortcuts/vc/vc_meeting_events.go

@@ -14,7 +14,8 @@ import (
 	"time"
 	"unicode"
 
-	"github.com/larksuite/cli/errs"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -36,7 +37,7 @@ func toUnixSeconds(input string, hint ...string) (string, error) {
 		return "", err
 	}
 	if _, err := strconv.ParseInt(ts, 10, 64); err != nil {
-		return "", fmt.Errorf("invalid timestamp %q: %w", ts, err) //nolint:forbidigo // intermediate parse error; callers wrap it into a typed ValidationError
+		return "", fmt.Errorf("invalid timestamp %q: %w", ts, err)
 	}
 	return ts, nil
 }
@@ -133,7 +134,7 @@ func meetingEventsPageSize(runtime *common.RuntimeContext) (int, error) {
 	}
 	pageSize, err := strconv.Atoi(pageSizeStr)
 	if err != nil {
-		return 0, errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --page-size %q: must be an integer", pageSizeStr).WithParam("--page-size")
+		return 0, common.FlagErrorf("invalid --page-size %q: must be an integer", pageSizeStr)
 	}
 	if pageSize < minVCMeetingEventsPageSize {
 		return minVCMeetingEventsPageSize, nil
@@ -154,11 +155,11 @@ func meetingEventsPaginationConfig(runtime *common.RuntimeContext) (bool, int) {
 func validateMeetingEventsMeetingID(meetingID string) error {
 	meetingID = strings.TrimSpace(meetingID)
 	if meetingID == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--meeting-id is required").WithParam("--meeting-id")
+		return common.FlagErrorf("--meeting-id is required")
 	}
 	value, err := strconv.ParseInt(meetingID, 10, 64)
 	if err != nil || value <= 0 {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--meeting-id must be a positive integer, got %q", meetingID).WithParam("--meeting-id")
+		return common.FlagErrorf("--meeting-id must be a positive integer, got %q", meetingID)
 	}
 	return nil
 }
@@ -175,14 +176,14 @@ func parseMeetingEventsTimeRange(runtime *common.RuntimeContext) (string, string
 	if start != "" {
 		parsed, err := toUnixSeconds(start)
 		if err != nil {
-			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start: %v", err).WithParam("--start")
+			return "", "", output.ErrValidation("--start: %v", err)
 		}
 		startTime = parsed
 	}
 	if end != "" {
 		parsed, err := toUnixSeconds(end, "end")
 		if err != nil {
-			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
+			return "", "", output.ErrValidation("--end: %v", err)
 		}
 		endTime = parsed
 	}
@@ -190,30 +191,29 @@ func parseMeetingEventsTimeRange(runtime *common.RuntimeContext) (string, string
 		startValue, _ := strconv.ParseInt(startTime, 10, 64)
 		endValue, _ := strconv.ParseInt(endTime, 10, 64)
 		if startValue > endValue {
-			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start (%s) is after --end (%s)", start, end).WithParam("--start")
+			return "", "", output.ErrValidation("--start (%s) is after --end (%s)", start, end)
 		}
 	}
 	return startTime, endTime, nil
 }
 
-func buildMeetingEventsParams(runtime *common.RuntimeContext, startTime, endTime string) (map[string]interface{}, error) {
+func buildMeetingEventsParams(runtime *common.RuntimeContext, startTime, endTime string) (larkcore.QueryParams, error) {
 	pageSize, err := meetingEventsPageSize(runtime)
 	if err != nil {
 		return nil, err
 	}
 
-	params := map[string]interface{}{
-		"meeting_id": strings.TrimSpace(runtime.Str("meeting-id")),
-		"page_size":  strconv.Itoa(pageSize),
-	}
+	params := make(larkcore.QueryParams)
+	params.Set("meeting_id", strings.TrimSpace(runtime.Str("meeting-id")))
+	params.Set("page_size", strconv.Itoa(pageSize))
 	if pageToken := strings.TrimSpace(runtime.Str("page-token")); pageToken != "" {
-		params["page_token"] = pageToken
+		params.Set("page_token", pageToken)
 	}
 	if startTime != "" {
-		params["start_time"] = startTime
+		params.Set("start_time", startTime)
 	}
 	if endTime != "" {
-		params["end_time"] = endTime
+		params.Set("end_time", endTime)
 	}
 	return params, nil
 }
@@ -225,7 +225,7 @@ func fetchMeetingEvents(ctx context.Context, runtime *common.RuntimeContext, sta
 	}
 	autoPaginate, pageLimit := meetingEventsPaginationConfig(runtime)
 	if !autoPaginate {
-		data, err := runtime.CallAPITyped(http.MethodGet, vcMeetingEventsAPIPath, params, nil)
+		data, err := runtime.DoAPIJSON(http.MethodGet, vcMeetingEventsAPIPath, params, nil)
 		if err != nil {
 			return nil, nil, false, "", err
 		}
@@ -245,7 +245,7 @@ func fetchMeetingEvents(ctx context.Context, runtime *common.RuntimeContext, sta
 		lastHasMore   bool
 	)
 	for page := 0; page < pageLimit; page++ {
-		data, err := runtime.CallAPITyped(http.MethodGet, vcMeetingEventsAPIPath, params, nil)
+		data, err := runtime.DoAPIJSON(http.MethodGet, vcMeetingEventsAPIPath, params, nil)
 		if err != nil {
 			return nil, nil, false, "", err
 		}
@@ -260,7 +260,7 @@ func fetchMeetingEvents(ctx context.Context, runtime *common.RuntimeContext, sta
 		if !lastHasMore || lastPageToken == "" {
 			break
 		}
-		params["page_token"] = lastPageToken
+		params.Set("page_token", lastPageToken)
 	}
 	if lastData == nil {
 		lastData = map[string]interface{}{}
@@ -271,11 +271,24 @@ func fetchMeetingEvents(ctx context.Context, runtime *common.RuntimeContext, sta
 	return lastData, allEvents, lastHasMore, lastPageToken, nil
 }
 
-func flattenQueryParams(params map[string]interface{}) map[string]interface{} {
+func flattenQueryParams(params larkcore.QueryParams) map[string]interface{} {
 	if len(params) == 0 {
 		return nil
 	}
-	return params
+	flat := make(map[string]interface{}, len(params))
+	for key, values := range params {
+		switch len(values) {
+		case 0:
+			continue
+		case 1:
+			flat[key] = values[0]
+		default:
+			copied := make([]string, len(values))
+			copy(copied, values)
+			flat[key] = copied
+		}
+	}
+	return flat
 }
 
 func compactMeetingEvents(events []interface{}) []interface{} {

shortcuts/vc/vc_meeting_events_test.go

@@ -5,7 +5,6 @@ package vc
 
 import (
 	"context"
-	"errors"
 	"reflect"
 	"strings"
 	"testing"
@@ -13,10 +12,10 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/shortcuts/common"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
 
 func newMeetingEventsRuntime() *common.RuntimeContext {
@@ -324,19 +323,19 @@ func TestBuildMeetingEventsParams(t *testing.T) {
 	if err != nil {
 		t.Fatalf("buildMeetingEventsParams() error = %v", err)
 	}
-	if got := params["meeting_id"]; got != "7628568141510692381" {
+	if got := params["meeting_id"][0]; got != "7628568141510692381" {
 		t.Fatalf("meeting_id = %q, want %q", got, "7628568141510692381")
 	}
-	if got := params["page_size"]; got != "40" {
+	if got := params["page_size"][0]; got != "40" {
 		t.Fatalf("page_size = %q, want %q", got, "40")
 	}
-	if got := params["page_token"]; got != "1710000000000000000" {
+	if got := params["page_token"][0]; got != "1710000000000000000" {
 		t.Fatalf("page_token = %q, want %q", got, "1710000000000000000")
 	}
-	if got := params["start_time"]; got != "1710000000" {
+	if got := params["start_time"][0]; got != "1710000000" {
 		t.Fatalf("start_time = %q, want %q", got, "1710000000")
 	}
-	if got := params["end_time"]; got != "1710003600" {
+	if got := params["end_time"][0]; got != "1710003600" {
 		t.Fatalf("end_time = %q, want %q", got, "1710003600")
 	}
 }
@@ -350,7 +349,7 @@ func TestBuildMeetingEventsParams_PageSizeBelowMinClampsToMin(t *testing.T) {
 	if err != nil {
 		t.Fatalf("buildMeetingEventsParams() error = %v", err)
 	}
-	if got := params["page_size"]; got != "20" {
+	if got := params["page_size"][0]; got != "20" {
 		t.Fatalf("page_size = %q, want %q when below min", got, "20")
 	}
 }
@@ -364,7 +363,7 @@ func TestBuildMeetingEventsParams_PageSizeAboveMaxClampsToMax(t *testing.T) {
 	if err != nil {
 		t.Fatalf("buildMeetingEventsParams() error = %v", err)
 	}
-	if got := params["page_size"]; got != "100" {
+	if got := params["page_size"][0]; got != "100" {
 		t.Fatalf("page_size = %q, want %q when above max", got, "100")
 	}
 }
@@ -379,7 +378,7 @@ func TestBuildMeetingEventsParams_PageAllUsesMaxPageSize(t *testing.T) {
 	if err != nil {
 		t.Fatalf("buildMeetingEventsParams() error = %v", err)
 	}
-	if got := params["page_size"]; got != "100" {
+	if got := params["page_size"][0]; got != "100" {
 		t.Fatalf("page_size = %q, want %q when page-all is set", got, "100")
 	}
 }
@@ -747,30 +746,22 @@ func TestFormatTimelineOffset(t *testing.T) {
 }
 
 func TestFlattenQueryParams(t *testing.T) {
-	params := map[string]interface{}{
-		"one":  "1",
-		"many": "2",
+	params := larkcore.QueryParams{
+		"one":   []string{"1"},
+		"many":  []string{"2", "3"},
+		"empty": []string{},
 	}
 
 	got := flattenQueryParams(params)
 	want := map[string]interface{}{
 		"one":  "1",
-		"many": "2",
+		"many": []string{"2", "3"},
 	}
 	if !reflect.DeepEqual(got, want) {
 		t.Fatalf("flattenQueryParams() = %#v, want %#v", got, want)
 	}
 }
 
-func TestFlattenQueryParams_NilOnEmpty(t *testing.T) {
-	if got := flattenQueryParams(nil); got != nil {
-		t.Fatalf("flattenQueryParams(nil) = %#v, want nil", got)
-	}
-	if got := flattenQueryParams(map[string]interface{}{}); got != nil {
-		t.Fatalf("flattenQueryParams(empty) = %#v, want nil", got)
-	}
-}
-
 func TestCompactMeetingPayload_DropsOnlyEmptySlices(t *testing.T) {
 	got := compactMeetingPayload(map[string]interface{}{
 		"empty_items": []interface{}{},
@@ -938,79 +929,3 @@ func TestNeedsColon(t *testing.T) {
 		}
 	}
 }
-
-// ---------------------------------------------------------------------------
-// Typed error lock assertions
-// ---------------------------------------------------------------------------
-
-func TestMeetingEvents_Validation_InvalidMeetingID_TypedError(t *testing.T) {
-	runtime := newMeetingEventsRuntime()
-	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "not-a-number")
-
-	err := VCMeetingEvents.Validate(context.Background(), runtime)
-	if err == nil {
-		t.Fatal("expected validation error")
-	}
-	if !strings.Contains(err.Error(), "positive integer") {
-		t.Errorf("message mismatch: %v", err)
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "--meeting-id" {
-		t.Errorf("Param = %q, want %q", ve.Param, "--meeting-id")
-	}
-}
-
-func TestMeetingEvents_Validation_InvalidPageSize_TypedError(t *testing.T) {
-	runtime := newMeetingEventsRuntime()
-	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "7628568141510692381")
-	mustSetMeetingEventsFlag(t, runtime, "page-size", "foo")
-
-	err := VCMeetingEvents.Validate(context.Background(), runtime)
-	if err == nil {
-		t.Fatal("expected validation error")
-	}
-	if !strings.Contains(err.Error(), "invalid --page-size") {
-		t.Errorf("message mismatch: %v", err)
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "--page-size" {
-		t.Errorf("Param = %q, want %q", ve.Param, "--page-size")
-	}
-}
-
-func TestMeetingEvents_Validation_StartAfterEnd_TypedError(t *testing.T) {
-	runtime := newMeetingEventsRuntime()
-	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "7628568141510692381")
-	mustSetMeetingEventsFlag(t, runtime, "start", "200")
-	mustSetMeetingEventsFlag(t, runtime, "end", "100")
-
-	err := VCMeetingEvents.Validate(context.Background(), runtime)
-	if err == nil {
-		t.Fatal("expected validation error")
-	}
-	if !strings.Contains(err.Error(), "after --end") {
-		t.Errorf("message mismatch: %v", err)
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "--start" {
-		t.Errorf("Param = %q, want %q", ve.Param, "--start")
-	}
-}

shortcuts/vc/vc_meeting_join.go

@@ -10,7 +10,6 @@ import (
 	"regexp"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -38,7 +37,7 @@ var VCMeetingJoin = common.Shortcut{
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		mn := strings.TrimSpace(runtime.Str("meeting-number"))
 		if !validMeetingNumber(mn) {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--meeting-number must be exactly 9 digits, got %q", mn).WithParam("--meeting-number")
+			return common.FlagErrorf("--meeting-number must be exactly 9 digits, got %q", mn)
 		}
 		return nil
 	},
@@ -50,7 +49,7 @@ var VCMeetingJoin = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		body := buildMeetingJoinBody(runtime)
-		data, err := runtime.CallAPITyped("POST", "/open-apis/vc/v1/bots/join", nil, body)
+		data, err := runtime.DoAPIJSON("POST", "/open-apis/vc/v1/bots/join", nil, body)
 		if err != nil {
 			return err
 		}

shortcuts/vc/vc_meeting_leave.go

@@ -9,7 +9,6 @@ import (
 	"io"
 	"strings"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -27,7 +26,7 @@ var VCMeetingLeave = common.Shortcut{
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("meeting-id")) == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--meeting-id is required").WithParam("--meeting-id")
+			return common.FlagErrorf("--meeting-id is required")
 		}
 		return nil
 	},
@@ -43,7 +42,7 @@ var VCMeetingLeave = common.Shortcut{
 		body := map[string]interface{}{
 			"meeting_id": meetingID,
 		}
-		data, err := runtime.CallAPITyped("POST", "/open-apis/vc/v1/bots/leave", nil, body)
+		data, err := runtime.DoAPIJSON("POST", "/open-apis/vc/v1/bots/leave", nil, body)
 		if err != nil {
 			return err
 		}

shortcuts/vc/vc_meeting_test.go

@@ -7,13 +7,11 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"errors"
 	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -579,67 +577,7 @@ func TestMeetingLeave_Execute_APIError(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for API failure")
 	}
-	// code 121005 classifies to a typed permission error (no edit/view rights).
-	p, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("expected a typed errs.* error, got %T: %v", err, err)
-	}
-	if p.Subtype != errs.SubtypePermissionDenied {
-		t.Errorf("subtype = %q, want %q", p.Subtype, errs.SubtypePermissionDenied)
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Typed error lock assertions
-// ---------------------------------------------------------------------------
-
-func TestMeetingJoin_Validate_InvalidFormat_TypedError(t *testing.T) {
-	cmd := &cobra.Command{Use: "test"}
-	cmd.Flags().String("meeting-number", "", "")
-	cmd.Flags().String("password", "", "")
-	_ = cmd.Flags().Set("meeting-number", "12345678") // 8 digits — invalid
-
-	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
-	err := VCMeetingJoin.Validate(context.Background(), runtime)
-	if err == nil {
-		t.Fatal("expected validation error")
-	}
-	if !strings.Contains(err.Error(), "9 digits") {
-		t.Errorf("message mismatch: %v", err)
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "--meeting-number" {
-		t.Errorf("Param = %q, want %q", ve.Param, "--meeting-number")
-	}
-}
-
-func TestMeetingLeave_Validate_WhitespaceOnly_TypedError(t *testing.T) {
-	cmd := &cobra.Command{Use: "test"}
-	cmd.Flags().String("meeting-id", "", "")
-	_ = cmd.Flags().Set("meeting-id", "   ")
-
-	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
-	err := VCMeetingLeave.Validate(context.Background(), runtime)
-	if err == nil {
-		t.Fatal("expected validation error")
-	}
-	if !strings.Contains(err.Error(), "meeting-id") {
-		t.Errorf("message mismatch: %v", err)
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "--meeting-id" {
-		t.Errorf("Param = %q, want %q", ve.Param, "--meeting-id")
+	if !strings.Contains(err.Error(), "no permission") {
+		t.Errorf("error should surface API message, got: %v", err)
 	}
 }

shortcuts/vc/vc_notes.go

@@ -23,6 +23,8 @@ import (
 	"strings"
 	"time"
 
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/auth"
@@ -72,13 +74,22 @@ const (
 )
 
 func minutesReadError(err error, minuteToken string) error {
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Code != minutesNoReadPermissionCode {
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil || exitErr.Detail.Code != minutesNoReadPermissionCode {
 		return err
 	}
-	p.Message = fmt.Sprintf("No read permission for minute %s: cannot query the minute.", minuteToken)
-	p.Hint = "Ask the minute owner for minute file read permission"
-	return err
+
+	return &output.ExitError{
+		Code: output.ExitAPI,
+		Detail: &output.ErrDetail{
+			Type:    "no_read_permission",
+			Code:    minutesNoReadPermissionCode,
+			Message: fmt.Sprintf("No read permission for minute %s: cannot query the minute.", minuteToken),
+			Hint:    "Ask the minute owner for minute file read permission",
+			Detail:  exitErr.Detail.Detail,
+		},
+		Err: err,
+	}
 }
 
 // validMinuteToken matches the server's minute-token format and blocks any
@@ -103,19 +114,19 @@ func sanitizeLogValue(s string) string {
 
 // getPrimaryCalendarID retrieves the current user's primary calendar ID.
 func getPrimaryCalendarID(runtime *common.RuntimeContext) (string, error) {
-	data, err := runtime.CallAPITyped(http.MethodPost, "/open-apis/calendar/v4/calendars/primary", nil, nil)
+	data, err := runtime.DoAPIJSON(http.MethodPost, "/open-apis/calendar/v4/calendars/primary", nil, nil)
 	if err != nil {
-		return "", err
+		return "", err // preserve original API error (with lark error code)
 	}
 	calendars, _ := data["calendars"].([]any)
 	if len(calendars) == 0 {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "primary calendar not found")
+		return "", output.ErrValidation("primary calendar not found")
 	}
 	first, _ := calendars[0].(map[string]any)
 	cal, _ := first["calendar"].(map[string]any)
 	calID, _ := cal["calendar_id"].(string)
 	if calID == "" {
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "primary calendar ID is empty")
+		return "", output.ErrValidation("primary calendar ID is empty")
 	}
 	return calID, nil
 }
@@ -138,23 +149,23 @@ func resolveMeetingIDsFromCalendarEvent(runtime *common.RuntimeContext, instance
 	if needNotes {
 		body["need_meeting_notes"] = true
 	}
-	data, err := runtime.CallAPITyped(http.MethodPost,
+	data, err := runtime.DoAPIJSON(http.MethodPost,
 		fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/mget_instance_relation_info", validate.EncodePathSegment(calendarID)),
 		nil,
 		body)
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("failed to query event relation info: %w", err)
 	}
 
 	infos, _ := data["instance_relation_infos"].([]any)
 	if len(infos) == 0 {
-		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "no event relation info found")
+		return nil, fmt.Errorf("no event relation info found")
 	}
 	info, _ := infos[0].(map[string]any)
 
 	rawIDs, _ := info["meeting_instance_ids"].([]any)
 	if len(rawIDs) == 0 {
-		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition, "no associated video meeting for this event")
+		return nil, fmt.Errorf("no associated video meeting for this event")
 	}
 
 	result := &eventRelationInfo{}
@@ -282,12 +293,13 @@ func asStringSlice(v any) []string {
 // Other failures fall back to the raw API error description so Agents can
 // still parse the underlying cause.
 func fetchMeetingMinuteToken(runtime *common.RuntimeContext, meetingID string) (token, errMsg string) {
-	data, err := runtime.CallAPITyped(http.MethodGet,
+	data, err := runtime.DoAPIJSON(http.MethodGet,
 		fmt.Sprintf("/open-apis/vc/v1/meetings/%s/recording", validate.EncodePathSegment(meetingID)),
 		nil, nil)
 	if err != nil {
-		if p, ok := errs.ProblemOf(err); ok {
-			switch p.Code {
+		var exitErr *output.ExitError
+		if errors.As(err, &exitErr) && exitErr.Detail != nil {
+			switch exitErr.Detail.Code {
 			case recordingNotFoundCode:
 				return "", "no minute file for this meeting"
 			case recordingNoPermissionCode:
@@ -316,8 +328,8 @@ func fetchMeetingMinuteToken(runtime *common.RuntimeContext, meetingID string) (
 // (semicolon-separated) so Agents always see all causes at once. The
 // `minute_token` field is only populated on success.
 func fetchNoteByMeetingID(ctx context.Context, runtime *common.RuntimeContext, meetingID string) map[string]any {
-	data, err := runtime.CallAPITyped(http.MethodGet, fmt.Sprintf("/open-apis/vc/v1/meetings/%s", validate.EncodePathSegment(meetingID)),
-		map[string]interface{}{"with_participants": "false", "query_mode": "0"}, nil)
+	data, err := runtime.DoAPIJSON(http.MethodGet, fmt.Sprintf("/open-apis/vc/v1/meetings/%s", validate.EncodePathSegment(meetingID)),
+		larkcore.QueryParams{"with_participants": []string{"false"}, "query_mode": []string{"0"}}, nil)
 	if err != nil {
 		return map[string]any{"meeting_id": meetingID, "error": fmt.Sprintf("failed to query meeting: %v", err)}
 	}
@@ -387,12 +399,13 @@ func hasNotesPayload(m map[string]any) bool {
 func fetchNoteByMinuteToken(ctx context.Context, runtime *common.RuntimeContext, minuteToken string) map[string]any {
 	errOut := runtime.IO().ErrOut
 
-	data, err := runtime.CallAPITyped(http.MethodGet, fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)), nil, nil)
+	data, err := runtime.DoAPIJSON(http.MethodGet, fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)), nil, nil)
 	if err != nil {
 		err = minutesReadError(err, minuteToken)
 		result := map[string]any{"minute_token": minuteToken, "error": err.Error()}
-		if p, ok := errs.ProblemOf(err); ok && p.Hint != "" {
-			result["hint"] = p.Hint
+		var exitErr *output.ExitError
+		if errors.As(err, &exitErr) && exitErr.Detail != nil && exitErr.Detail.Hint != "" {
+			result["hint"] = exitErr.Detail.Hint
 		}
 		return result
 	}
@@ -456,7 +469,7 @@ func sanitizeDirName(title, minuteToken string) string {
 func fetchInlineArtifacts(runtime *common.RuntimeContext, minuteToken string, title string, result map[string]any) {
 	errOut := runtime.IO().ErrOut
 	fmt.Fprintf(errOut, "%s fetching AI artifacts...\n", logPrefix)
-	data, err := runtime.CallAPITyped(http.MethodGet, fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/artifacts", validate.EncodePathSegment(minuteToken)), nil, nil)
+	data, err := runtime.DoAPIJSON(http.MethodGet, fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/artifacts", validate.EncodePathSegment(minuteToken)), nil, nil)
 	if err != nil {
 		fmt.Fprintf(errOut, "%s failed to fetch AI artifacts: %v\n", logPrefix, err)
 		return
@@ -569,10 +582,11 @@ func extractDocTokens(refs []any) []string {
 
 // fetchNoteDetail retrieves note document tokens via note_id.
 func fetchNoteDetail(_ context.Context, runtime *common.RuntimeContext, noteID string) map[string]any {
-	data, err := runtime.CallAPITyped(http.MethodGet, fmt.Sprintf("/open-apis/vc/v1/notes/%s", validate.EncodePathSegment(noteID)), nil, nil)
+	data, err := runtime.DoAPIJSON(http.MethodGet, fmt.Sprintf("/open-apis/vc/v1/notes/%s", validate.EncodePathSegment(noteID)), nil, nil)
 	if err != nil {
-		if p, ok := errs.ProblemOf(err); ok && p.Code == noteNoPermissionCode {
-			return map[string]any{"error": fmt.Sprintf("[%v]: no read permission for this meeting note", p.Code)}
+		var exitErr *output.ExitError
+		if errors.As(err, &exitErr) && exitErr.Detail != nil && exitErr.Detail.Code == noteNoPermissionCode {
+			return map[string]any{"error": fmt.Sprintf("[%v]: no read permission for this meeting note", exitErr.Detail.Code)}
 		}
 		return map[string]any{"error": fmt.Sprintf("failed to query note detail: %v", err)}
 	}
@@ -616,7 +630,7 @@ var VCNotes = common.Shortcut{
 		{Name: "overwrite", Type: "bool", Desc: "overwrite existing artifact files"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		if err := common.ExactlyOneTyped(runtime, "meeting-ids", "minute-tokens", "calendar-event-ids"); err != nil {
+		if err := common.ExactlyOne(runtime, "meeting-ids", "minute-tokens", "calendar-event-ids"); err != nil {
 			return err
 		}
 		// batch input size limit
@@ -624,12 +638,12 @@ var VCNotes = common.Shortcut{
 		for _, flag := range []string{"meeting-ids", "minute-tokens", "calendar-event-ids"} {
 			if v := runtime.Str(flag); v != "" {
 				if ids := common.SplitCSV(v); len(ids) > maxBatchSize {
-					return errs.NewValidationError(errs.SubtypeInvalidArgument, "--%s: too many IDs (%d), maximum is %d", flag, len(ids), maxBatchSize).WithParam("--" + flag)
+					return output.ErrValidation("--%s: too many IDs (%d), maximum is %d", flag, len(ids), maxBatchSize)
 				}
 			}
 		}
 		if outDir := runtime.Str("output-dir"); outDir != "" {
-			if err := common.ValidateSafePathTyped(runtime.FileIO(), outDir); err != nil {
+			if err := common.ValidateSafePath(runtime.FileIO(), outDir); err != nil {
 				return err
 			}
 		}
@@ -637,7 +651,7 @@ var VCNotes = common.Shortcut{
 		if v := runtime.Str("minute-tokens"); v != "" {
 			for _, token := range common.SplitCSV(v) {
 				if !validMinuteToken.MatchString(token) {
-					return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid minute token %q: must contain only lowercase alphanumeric characters", token).WithParam("--minute-tokens")
+					return output.ErrValidation("invalid minute token %q: must contain only lowercase alphanumeric characters", token)
 				}
 			}
 		}
@@ -758,7 +772,9 @@ var VCNotes = common.Shortcut{
 
 		// all failed → return structured error
 		if successCount == 0 && len(results) > 0 {
-			return runtime.OutPartialFailure(map[string]any{"notes": results}, &output.Meta{Count: len(results)})
+			outData := map[string]any{"notes": results}
+			runtime.OutFormat(outData, &output.Meta{Count: len(results)}, nil)
+			return output.ErrAPI(0, fmt.Sprintf("all %d queries failed", len(results)), nil)
 		}
 
 		// output

shortcuts/vc/vc_notes_test.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
-	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -17,11 +16,9 @@ import (
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -252,25 +249,11 @@ func TestNotes_Validation_ExactlyOne(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected validation error for no flags")
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-	}
 
 	err = mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m1", "--minute-tokens", "t1", "--as", "user"}, f, nil)
 	if err == nil {
 		t.Fatal("expected validation error for two flags")
 	}
-	ve = nil
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-	}
 }
 
 func TestNotes_DryRun_MeetingIDs(t *testing.T) {
@@ -1023,18 +1006,11 @@ func TestNotes_MeetingPath_BothFail_ErrorJoinedWithSemicolon(t *testing.T) {
 	reg.Register(meetingGetStub("m_bothfail", ""))
 	reg.Register(recordingErrStub("m_bothfail", 121004, "data not found"))
 
-	// Two-path failure with no payload should make the batch return OutPartialFailure.
+	// Two-path failure with no payload should make the batch return ErrAPI.
 	err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_bothfail", "--as", "user"}, f, stdout)
 	if err == nil {
 		t.Fatalf("expected batch failure error, got nil")
 	}
-	var pfErr *output.PartialFailureError
-	if !errors.As(err, &pfErr) {
-		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
-	}
-	if pfErr.Code != output.ExitAPI {
-		t.Errorf("PartialFailureError.Code = %d, want ExitAPI (%d)", pfErr.Code, output.ExitAPI)
-	}
 
 	note := extractFirstNote(t, stdout)
 	assertNoteFieldAbsent(t, note, "minute_token")
@@ -1068,13 +1044,6 @@ func TestNotes_MeetingPath_NoteNoPermission_FriendlyHint(t *testing.T) {
 	if err == nil {
 		t.Fatalf("expected batch failure error, got nil")
 	}
-	var pfErr *output.PartialFailureError
-	if !errors.As(err, &pfErr) {
-		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
-	}
-	if pfErr.Code != output.ExitAPI {
-		t.Errorf("PartialFailureError.Code = %d, want ExitAPI (%d)", pfErr.Code, output.ExitAPI)
-	}
 
 	note := extractFirstNote(t, stdout)
 	assertNoteFieldAbsent(t, note, "note_doc_token", "minute_token")
@@ -1084,249 +1053,3 @@ func TestNotes_MeetingPath_NoteNoPermission_FriendlyHint(t *testing.T) {
 		"; ", // note + minute causes joined with semicolon
 	)
 }
-
-// ---------------------------------------------------------------------------
-// Typed-error lock: errs.ValidationError assertions
-// ---------------------------------------------------------------------------
-
-func TestNotes_BatchLimit_TypedValidationError(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
-	ids := make([]string, 51)
-	for i := range ids {
-		ids[i] = fmt.Sprintf("m%d", i)
-	}
-	err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", strings.Join(ids, ","), "--as", "user"}, f, nil)
-	if err == nil {
-		t.Fatal("expected batch limit error")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-	}
-	if !strings.HasPrefix(ve.Param, "--") {
-		t.Errorf("Param = %q, want prefix '--'", ve.Param)
-	}
-}
-
-func TestNotes_InvalidMinuteToken_TypedValidationError(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
-	err := mountAndRun(t, VCNotes, []string{"+notes", "--minute-tokens", "INVALID_TOKEN!", "--as", "user"}, f, nil)
-	if err == nil {
-		t.Fatal("expected validation error for invalid minute token")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-	}
-	if ve.Param != "--minute-tokens" {
-		t.Errorf("Param = %q, want --minute-tokens", ve.Param)
-	}
-}
-
-func TestResolveMeetingIDs_NoRelationInfo_TypedValidationError(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	// mget returns empty instance_relation_infos
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/calendar/v4/calendars/cal_x/events/mget_instance_relation_info",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"instance_relation_infos": []interface{}{},
-			},
-		},
-	})
-
-	if err := botExec(t, "no-rel-info", f, func(_ context.Context, rctx *common.RuntimeContext) error {
-		_, err := resolveMeetingIDsFromCalendarEvent(rctx, "evt_x", "cal_x", false)
-		if err == nil {
-			t.Fatal("expected error for empty instance_relation_infos")
-		}
-		var ve *errs.ValidationError
-		if !errors.As(err, &ve) {
-			t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-		}
-		if ve.Subtype != errs.SubtypeFailedPrecondition {
-			t.Errorf("Subtype = %q, want SubtypeFailedPrecondition", ve.Subtype)
-		}
-		if !strings.Contains(ve.Error(), "no event relation info found") {
-			t.Errorf("message = %q, want contains 'no event relation info found'", ve.Error())
-		}
-		return nil
-	}); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-}
-
-func TestResolveMeetingIDs_NoMeetingIDs_TypedValidationError(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	// mget returns one info entry but with no meeting_instance_ids
-	reg.Register(&httpmock.Stub{
-		Method: "POST",
-		URL:    "/open-apis/calendar/v4/calendars/cal_y/events/mget_instance_relation_info",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"instance_relation_infos": []interface{}{
-					map[string]interface{}{
-						"instance_id":          "evt_y",
-						"meeting_instance_ids": []interface{}{},
-					},
-				},
-			},
-		},
-	})
-
-	if err := botExec(t, "no-meeting-ids", f, func(_ context.Context, rctx *common.RuntimeContext) error {
-		_, err := resolveMeetingIDsFromCalendarEvent(rctx, "evt_y", "cal_y", false)
-		if err == nil {
-			t.Fatal("expected error for empty meeting_instance_ids")
-		}
-		var ve *errs.ValidationError
-		if !errors.As(err, &ve) {
-			t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-		}
-		if ve.Subtype != errs.SubtypeFailedPrecondition {
-			t.Errorf("Subtype = %q, want SubtypeFailedPrecondition", ve.Subtype)
-		}
-		if !strings.Contains(ve.Error(), "no associated video meeting for this event") {
-			t.Errorf("message = %q, want contains 'no associated video meeting for this event'", ve.Error())
-		}
-		return nil
-	}); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Typed-error lock: enrichment via errs.ProblemOf
-// ---------------------------------------------------------------------------
-
-// minuteGetErrStub returns an error stub for the minutes API.
-func minuteGetErrStub(token string, code int, msg string) *httpmock.Stub {
-	return &httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/minutes/v1/minutes/" + token,
-		Body:   map[string]any{"code": code, "msg": msg},
-	}
-}
-
-// TestMinutesReadError_ProblemOf_EnrichesMessage pins that minutesReadError
-// mutates the typed error's Message and Hint in-place via errs.ProblemOf when
-// the server returns code 2091005 (minutes no-read-permission).
-func TestMinutesReadError_ProblemOf_EnrichesMessage(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	reg.Register(minuteGetErrStub("tokperm", minutesNoReadPermissionCode, "no permission"))
-	// artifactsStub not needed: we never reach it on error
-
-	// A single minute-token that fails on a no-read-permission code still
-	// produces a note carrying minute_token, so the batch exits 0 with the
-	// enriched error surfaced inline rather than becoming an all-fail.
-	if err := mountAndRun(t, VCNotes, []string{"+notes", "--minute-tokens", "tokperm", "--as", "user"}, f, stdout); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	// stdout carries the note with the enriched error/hint
-	var resp map[string]any
-	if parseErr := json.Unmarshal(stdout.Bytes(), &resp); parseErr != nil {
-		t.Fatalf("unmarshal stdout: %v\n%s", parseErr, stdout.String())
-	}
-	data, _ := resp["data"].(map[string]any)
-	notes, _ := data["notes"].([]any)
-	if len(notes) != 1 {
-		t.Fatalf("expected 1 note, got %d", len(notes))
-	}
-	note, _ := notes[0].(map[string]any)
-
-	errMsg, _ := note["error"].(string)
-	if !strings.Contains(errMsg, "No read permission for minute tokperm") {
-		t.Errorf("error message not enriched: %q", errMsg)
-	}
-	hint, _ := note["hint"].(string)
-	if !strings.Contains(hint, "minute file read permission") {
-		t.Errorf("hint not surfaced: %q", hint)
-	}
-}
-
-// TestFetchNoteDetail_NoteNoPermission_ProblemOf pins that fetchNoteDetail
-// returns a friendly error map when CallAPITyped returns code 121005 and
-// ProblemOf can extract it.
-func TestFetchNoteDetail_NoteNoPermission_ProblemOf(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
-
-	// meeting.get returns note_id, note detail returns 121005
-	reg.Register(meetingGetStub("m_noteperm2", "note_perm2"))
-	reg.Register(noteDetailErrStub("note_perm2", noteNoPermissionCode, "no permission"))
-	reg.Register(recordingOKStub("m_noteperm2", "https://meetings.feishu.cn/minutes/obcpermtest"))
-
-	// note fails but minute_token succeeds → partial success (hasNotesPayload=true)
-	err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_noteperm2", "--as", "user"}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error (expected partial success): %v", err)
-	}
-	note := extractFirstNote(t, stdout)
-
-	// minute_token succeeded so hasNotesPayload=true; note error still surfaced
-	if got := note["minute_token"]; got != "obcpermtest" {
-		t.Errorf("minute_token = %v, want obcpermtest", got)
-	}
-	errMsg, _ := note["error"].(string)
-	if !strings.Contains(errMsg, "[121005]") || !strings.Contains(errMsg, "no read permission for this meeting note") {
-		t.Errorf("fetchNoteDetail permission error = %q; want contains '[121005]: no read permission for this meeting note'", errMsg)
-	}
-}
-
-// TestNotes_AllFailed_OutPartialFailure pins that when every item in the batch
-// fails (successCount == 0), Execute returns *output.PartialFailureError with
-// ExitAPI code, and stdout still carries the ok:false envelope with notes data.
-func TestNotes_AllFailed_OutPartialFailure(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
-
-	// Both meetings have no note_id and recording returns 121004 (no minute file)
-	// → hasNotesPayload == false for both → successCount == 0
-	reg.Register(meetingGetStub("m_fail1", ""))
-	reg.Register(recordingErrStub("m_fail1", 121004, "not found"))
-	reg.Register(meetingGetStub("m_fail2", ""))
-	reg.Register(recordingErrStub("m_fail2", 121004, "not found"))
-
-	err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_fail1,m_fail2", "--as", "user"}, f, stdout)
-	if err == nil {
-		t.Fatal("expected batch failure error, got nil")
-	}
-
-	// typed partial-failure exit signal
-	var pfErr *output.PartialFailureError
-	if !errors.As(err, &pfErr) {
-		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
-	}
-	if pfErr.Code != output.ExitAPI {
-		t.Errorf("PartialFailureError.Code = %d, want ExitAPI (%d)", pfErr.Code, output.ExitAPI)
-	}
-
-	// stdout carries ok:false envelope with both failed notes
-	var env struct {
-		OK   bool                   `json:"ok"`
-		Data map[string]interface{} `json:"data"`
-	}
-	if parseErr := json.Unmarshal(stdout.Bytes(), &env); parseErr != nil {
-		t.Fatalf("unmarshal stdout: %v\n%s", parseErr, stdout.String())
-	}
-	if env.OK {
-		t.Errorf("ok must be false on all-fail, got ok:true")
-	}
-	notes, _ := env.Data["notes"].([]interface{})
-	if len(notes) != 2 {
-		t.Fatalf("expected 2 notes in data, got %d\nstdout: %s", len(notes), stdout.String())
-	}
-}

shortcuts/vc/vc_recording.go

@@ -18,7 +18,6 @@ import (
 	"strings"
 	"time"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/internal/validate"
@@ -56,7 +55,7 @@ func extractMinuteToken(recordingURL string) string {
 
 // fetchRecordingByMeetingID queries recording info for a single meeting.
 func fetchRecordingByMeetingID(_ context.Context, runtime *common.RuntimeContext, meetingID string) map[string]any {
-	data, err := runtime.CallAPITyped(http.MethodGet,
+	data, err := runtime.DoAPIJSON(http.MethodGet,
 		fmt.Sprintf("/open-apis/vc/v1/meetings/%s/recording", validate.EncodePathSegment(meetingID)),
 		nil, nil)
 	if err != nil {
@@ -98,14 +97,14 @@ var VCRecording = common.Shortcut{
 		{Name: "calendar-event-ids", Desc: "calendar event instance IDs, comma-separated for batch"},
 	},
 	Validate: func(_ context.Context, runtime *common.RuntimeContext) error {
-		if err := common.ExactlyOneTyped(runtime, "meeting-ids", "calendar-event-ids"); err != nil {
+		if err := common.ExactlyOne(runtime, "meeting-ids", "calendar-event-ids"); err != nil {
 			return err
 		}
 		const maxBatchSize = 50
 		for _, flag := range []string{"meeting-ids", "calendar-event-ids"} {
 			if v := runtime.Str(flag); v != "" {
 				if ids := common.SplitCSV(v); len(ids) > maxBatchSize {
-					return errs.NewValidationError(errs.SubtypeInvalidArgument, "--%s: too many IDs (%d), maximum is %d", flag, len(ids), maxBatchSize).WithParam("--" + flag)
+					return output.ErrValidation("--%s: too many IDs (%d), maximum is %d", flag, len(ids), maxBatchSize)
 				}
 			}
 		}
@@ -122,11 +121,9 @@ var VCRecording = common.Shortcut{
 			stored := auth.GetStoredToken(appID, userOpenID)
 			if stored != nil {
 				if missing := auth.MissingScopes(stored.Scope, required); len(missing) > 0 {
-					return errs.NewPermissionError(errs.SubtypeMissingScope,
-						"missing required scope(s): %s", strings.Join(missing, ", ")).
-						WithHint("run `lark-cli auth login --scope %q` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", strings.Join(missing, " ")).
-						WithMissingScopes(missing...).
-						WithIdentity(string(runtime.As()))
+					return output.ErrWithHint(output.ExitAuth, "missing_scope",
+						fmt.Sprintf("missing required scope(s): %s", strings.Join(missing, ", ")),
+						fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.", strings.Join(missing, " ")))
 				}
 			}
 		}
@@ -215,7 +212,9 @@ var VCRecording = common.Shortcut{
 		fmt.Fprintf(errOut, "%s done: %d total, %d succeeded, %d failed\n", recordingLogPrefix, len(results), successCount, len(results)-successCount)
 
 		if successCount == 0 && len(results) > 0 {
-			return runtime.OutPartialFailure(map[string]any{"recordings": results}, &output.Meta{Count: len(results)})
+			outData := map[string]any{"recordings": results}
+			runtime.OutFormat(outData, &output.Meta{Count: len(results)}, nil)
+			return output.ErrAPI(0, fmt.Sprintf("all %d queries failed", len(results)), nil)
 		}
 
 		outData := map[string]any{"recordings": results}

shortcuts/vc/vc_recording_test.go

@@ -5,21 +5,14 @@ package vc
 
 import (
 	"context"
-	"encoding/json"
-	"errors"
 	"fmt"
 	"strings"
 	"testing"
-	"time"
 
 	"github.com/spf13/cobra"
-	keyring "github.com/zalando/go-keyring"
 
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/auth"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -68,26 +61,12 @@ func TestRecording_Validation_ExactlyOne(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected validation error for no flags")
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-	}
 
 	// 两个 flag 都传了
 	err = mountAndRun(t, VCRecording, []string{"+recording", "--meeting-ids", "m1", "--calendar-event-ids", "e1", "--as", "user"}, f, nil)
 	if err == nil {
 		t.Fatal("expected validation error for two flags")
 	}
-	ve = nil
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
-	}
 }
 
 func TestRecording_BatchLimit_MeetingIDs(t *testing.T) {
@@ -103,16 +82,6 @@ func TestRecording_BatchLimit_MeetingIDs(t *testing.T) {
 	if !strings.Contains(err.Error(), "too many IDs") {
 		t.Errorf("expected 'too many IDs' error, got: %v", err)
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("expected subtype %q, got %q", errs.SubtypeInvalidArgument, ve.Subtype)
-	}
-	if !strings.HasPrefix(ve.Param, "--") {
-		t.Errorf("expected Param to start with '--', got %q", ve.Param)
-	}
 }
 
 func TestRecording_BatchLimit_CalendarEventIDs(t *testing.T) {
@@ -128,65 +97,6 @@ func TestRecording_BatchLimit_CalendarEventIDs(t *testing.T) {
 	if !strings.Contains(err.Error(), "too many IDs") {
 		t.Errorf("expected 'too many IDs' error, got: %v", err)
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("expected subtype %q, got %q", errs.SubtypeInvalidArgument, ve.Subtype)
-	}
-	if !strings.HasPrefix(ve.Param, "--") {
-		t.Errorf("expected Param to start with '--', got %q", ve.Param)
-	}
-}
-
-func TestRecording_Validate_MissingScope(t *testing.T) {
-	keyring.MockInit() // use in-memory keyring to avoid macOS keychain popups
-	t.Setenv("HOME", t.TempDir())
-
-	cfg := defaultConfig()
-	// Store a token that intentionally lacks the vc:record:readonly scope.
-	token := &auth.StoredUAToken{
-		UserOpenId:       cfg.UserOpenId,
-		AppId:            cfg.AppID,
-		AccessToken:      "test-user-access-token",
-		RefreshToken:     "test-refresh-token",
-		ExpiresAt:        time.Now().Add(1 * time.Hour).UnixMilli(),
-		RefreshExpiresAt: time.Now().Add(24 * time.Hour).UnixMilli(),
-		Scope:            "calendar:calendar:read",
-		GrantedAt:        time.Now().Add(-1 * time.Hour).UnixMilli(),
-	}
-	if err := auth.SetStoredToken(token); err != nil {
-		t.Fatalf("SetStoredToken() error = %v", err)
-	}
-	t.Cleanup(func() { _ = auth.RemoveStoredToken(cfg.AppID, cfg.UserOpenId) })
-
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	err := mountAndRun(t, VCRecording, []string{"+recording", "--meeting-ids", "m001", "--as", "user"}, f, nil)
-	if err == nil {
-		t.Fatal("expected missing_scope error, got nil")
-	}
-
-	var pe *errs.PermissionError
-	if !errors.As(err, &pe) {
-		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
-	}
-	if pe.Subtype != errs.SubtypeMissingScope {
-		t.Errorf("expected subtype %q, got %q", errs.SubtypeMissingScope, pe.Subtype)
-	}
-	if !strings.Contains(err.Error(), "missing required scope") {
-		t.Errorf("expected 'missing required scope' in message, got: %v", err)
-	}
-	found := false
-	for _, s := range pe.MissingScopes {
-		if s == "vc:record:readonly" {
-			found = true
-			break
-		}
-	}
-	if !found {
-		t.Errorf("expected MissingScopes to contain 'vc:record:readonly', got %v", pe.MissingScopes)
-	}
 }
 
 // ---------------------------------------------------------------------------
@@ -788,10 +698,8 @@ func TestRecording_Execute_AllFailed_ErrorMessage(t *testing.T) {
 		if !strings.Contains(e1, "data not found") {
 			t.Errorf("m001 error should contain API message, got: %s", e1)
 		}
-		// code 121005 classifies to a typed permission error; the embedded
-		// result string surfaces the permission cause.
-		if !strings.Contains(e2, "permission") {
-			t.Errorf("m002 error should surface the permission failure, got: %s", e2)
+		if !strings.Contains(e2, "no permission") {
+			t.Errorf("m002 error should contain API message, got: %s", e2)
 		}
 		if r1["meeting_id"] != "m001" {
 			t.Errorf("error result should preserve meeting_id, got: %v", r1["meeting_id"])
@@ -865,59 +773,3 @@ func TestRecording_Execute_RecordingGenerating(t *testing.T) {
 		t.Fatalf("unexpected error: %v", err)
 	}
 }
-
-// TestRecording_Execute_AllFailed_OutPartialFailure exercises the full
-// VCRecording.Execute path via mountAndRun when every query fails.
-// The batch should surface as an ok:false envelope on stdout (OutPartialFailure)
-// carrying the per-item failures under data.recordings, and return a typed
-// *output.PartialFailureError (ExitAPI) — no legacy ErrAPI / "all N queries failed".
-func TestRecording_Execute_AllFailed_OutPartialFailure(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
-
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/vc/v1/meetings/m001/recording",
-		Body:   map[string]interface{}{"code": 121004, "msg": "data not found"},
-	})
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/vc/v1/meetings/m002/recording",
-		Body:   map[string]interface{}{"code": 121005, "msg": "no permission"},
-	})
-
-	err := mountAndRun(t, VCRecording,
-		[]string{"+recording", "--meeting-ids", "m001,m002", "--format", "json", "--as", "user"},
-		f, stdout)
-
-	// 1. typed partial-failure exit signal — not a legacy ErrAPI string
-	var pfErr *output.PartialFailureError
-	if !errors.As(err, &pfErr) {
-		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
-	}
-	if pfErr.Code != output.ExitAPI {
-		t.Errorf("exit code = %d, want %d (ExitAPI)", pfErr.Code, output.ExitAPI)
-	}
-
-	// 2. stdout envelope: ok:false, data.recordings carries both failed items
-	raw := stdout.Bytes()
-	var env struct {
-		OK   bool `json:"ok"`
-		Data struct {
-			Recordings []map[string]interface{} `json:"recordings"`
-		} `json:"data"`
-	}
-	if jsonErr := json.Unmarshal(raw, &env); jsonErr != nil {
-		t.Fatalf("unmarshal stdout: %v\nraw=%s", jsonErr, string(raw))
-	}
-	if env.OK {
-		t.Errorf("envelope ok must be false on all-failed batch, got ok:true\nstdout: %s", string(raw))
-	}
-	if len(env.Data.Recordings) != 2 {
-		t.Fatalf("expected 2 failed items in data.recordings, got %d\nstdout: %s", len(env.Data.Recordings), string(raw))
-	}
-	for _, rec := range env.Data.Recordings {
-		if rec["error"] == nil {
-			t.Errorf("each failed item must carry an error field; item: %v", rec)
-		}
-	}
-}

shortcuts/vc/vc_search.go

@@ -12,9 +12,9 @@ import (
 	"time"
 	"unicode/utf8"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 )
 
 const (
@@ -31,7 +31,7 @@ func toRFC3339(input string, hint ...string) (string, error) {
 	}
 	sec, err := strconv.ParseInt(ts, 10, 64)
 	if err != nil {
-		return "", fmt.Errorf("invalid timestamp %q: %w", ts, err) //nolint:forbidigo // intermediate parse error; callers wrap it into a typed ValidationError
+		return "", fmt.Errorf("invalid timestamp %q: %w", ts, err)
 	}
 	return time.Unix(sec, 0).Format(time.RFC3339), nil
 }
@@ -47,14 +47,14 @@ func parseTimeRange(runtime *common.RuntimeContext) (string, string, error) {
 	if start != "" {
 		parsed, err := toRFC3339(start)
 		if err != nil {
-			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start: %v", err).WithParam("--start")
+			return "", "", output.ErrValidation("--start: %v", err)
 		}
 		startTime = parsed
 	}
 	if end != "" {
 		parsed, err := toRFC3339(end, "end")
 		if err != nil {
-			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
+			return "", "", output.ErrValidation("--end: %v", err)
 		}
 		endTime = parsed
 	}
@@ -63,7 +63,7 @@ func parseTimeRange(runtime *common.RuntimeContext) (string, string, error) {
 		st, _ := time.Parse(time.RFC3339, startTime)
 		et, _ := time.Parse(time.RFC3339, endTime)
 		if st.After(et) {
-			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start (%s) is after --end (%s)", start, end).WithParam("--start")
+			return "", "", output.ErrValidation("--start (%s) is after --end (%s)", start, end)
 		}
 	}
 	return startTime, endTime, nil
@@ -138,16 +138,16 @@ func buildSearchBody(runtime *common.RuntimeContext, startTime, endTime string)
 	return body
 }
 
-func buildSearchParams(runtime *common.RuntimeContext) map[string]interface{} {
-	params := map[string]interface{}{}
+func buildSearchParams(runtime *common.RuntimeContext) larkcore.QueryParams {
+	params := larkcore.QueryParams{}
 	pageToken := strings.TrimSpace(runtime.Str("page-token"))
 	pageSize, _ := strconv.Atoi(strings.TrimSpace(runtime.Str("page-size")))
 	if pageSize <= 0 {
 		pageSize = defaultVCSearchPageSize
 	}
-	params["page_size"] = strconv.Itoa(pageSize)
+	params["page_size"] = []string{strconv.Itoa(pageSize)}
 	if pageToken != "" {
-		params["page_token"] = pageToken
+		params["page_token"] = []string{pageToken}
 	}
 	return params
 }
@@ -192,9 +192,9 @@ var VCSearch = common.Shortcut{
 			return err
 		}
 		if q := strings.TrimSpace(runtime.Str("query")); q != "" && utf8.RuneCountInString(q) > maxVCSearchQueryLen {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--query: length must be between 1 and 50 characters").WithParam("--query")
+			return output.ErrValidation("--query: length must be between 1 and 50 characters")
 		}
-		if _, err := common.ValidatePageSizeTyped(runtime, "page-size", defaultVCSearchPageSize, 1, maxVCSearchPageSize); err != nil {
+		if _, err := common.ValidatePageSize(runtime, "page-size", defaultVCSearchPageSize, 1, maxVCSearchPageSize); err != nil {
 			return err
 		}
 		for _, flag := range []string{"query", "start", "end", "organizer-ids", "participant-ids", "room-ids"} {
@@ -202,7 +202,7 @@ var VCSearch = common.Shortcut{
 				return nil
 			}
 		}
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify at least one of --query, --start, --end, --organizer-ids, --participant-ids, or --room-ids")
+		return common.FlagErrorf("specify at least one of --query, --start, --end, --organizer-ids, --participant-ids, or --room-ids")
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		startTime, endTime, err := parseTimeRange(runtime)
@@ -210,10 +210,20 @@ var VCSearch = common.Shortcut{
 			return common.NewDryRunAPI().Set("error", err.Error())
 		}
 		params := buildSearchParams(runtime)
+		dryRunParams := map[string]interface{}{}
+		for key, values := range params {
+			if len(values) == 1 {
+				dryRunParams[key] = values[0]
+			} else if len(values) > 1 {
+				vs := make([]string, len(values))
+				copy(vs, values)
+				dryRunParams[key] = vs
+			}
+		}
 		dryRun := common.NewDryRunAPI().
 			POST("/open-apis/vc/v1/meetings/search")
-		if len(params) > 0 {
-			dryRun.Params(params)
+		if len(dryRunParams) > 0 {
+			dryRun.Params(dryRunParams)
 		}
 		return dryRun.Body(buildSearchBody(runtime, startTime, endTime))
 	},
@@ -222,7 +232,7 @@ var VCSearch = common.Shortcut{
 		if err != nil {
 			return err
 		}
-		data, err := runtime.CallAPITyped("POST", "/open-apis/vc/v1/meetings/search", buildSearchParams(runtime), buildSearchBody(runtime, startTime, endTime))
+		data, err := runtime.DoAPIJSON("POST", "/open-apis/vc/v1/meetings/search", buildSearchParams(runtime), buildSearchBody(runtime, startTime, endTime))
 		if err != nil {
 			return err
 		}

shortcuts/vc/vc_search_test.go

@@ -5,13 +5,11 @@ package vc
 
 import (
 	"context"
-	"errors"
 	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 
-	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -241,16 +239,6 @@ func TestSearch_Validation_InvalidPageSize(t *testing.T) {
 	if !strings.Contains(err.Error(), "must be between 1 and 30") {
 		t.Fatalf("unexpected error message: %v", err)
 	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "--page-size" {
-		t.Fatalf("Param = %q, want --page-size", ve.Param)
-	}
 }
 
 func TestSearch_DryRun(t *testing.T) {
@@ -271,182 +259,3 @@ func TestSearch_InvalidTimeRange(t *testing.T) {
 		t.Fatal("expected error for invalid time")
 	}
 }
-
-// ---------------------------------------------------------------------------
-// Typed error envelope assertions (errs migration lock-in)
-// ---------------------------------------------------------------------------
-
-func TestParseTimeRange_InvalidStart_TypedError(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "test", AppSecret: "s", Brand: core.BrandFeishu}
-	cmd := &cobra.Command{Use: "test"}
-	cmd.Flags().String("start", "", "")
-	cmd.Flags().String("end", "", "")
-	_ = cmd.Flags().Set("start", "not-a-date")
-	runtime := common.TestNewRuntimeContext(cmd, cfg)
-
-	_, _, err := parseTimeRange(runtime)
-	if err == nil {
-		t.Fatal("expected error for invalid --start")
-	}
-	if !strings.Contains(err.Error(), "--start:") {
-		t.Errorf("message should contain '--start:', got: %v", err)
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "--start" {
-		t.Errorf("Param = %q, want \"--start\"", ve.Param)
-	}
-}
-
-func TestParseTimeRange_InvalidEnd_TypedError(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "test", AppSecret: "s", Brand: core.BrandFeishu}
-	cmd := &cobra.Command{Use: "test"}
-	cmd.Flags().String("start", "", "")
-	cmd.Flags().String("end", "", "")
-	_ = cmd.Flags().Set("end", "not-a-date")
-	runtime := common.TestNewRuntimeContext(cmd, cfg)
-
-	_, _, err := parseTimeRange(runtime)
-	if err == nil {
-		t.Fatal("expected error for invalid --end")
-	}
-	if !strings.Contains(err.Error(), "--end:") {
-		t.Errorf("message should contain '--end:', got: %v", err)
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "--end" {
-		t.Errorf("Param = %q, want \"--end\"", ve.Param)
-	}
-}
-
-func TestParseTimeRange_StartAfterEnd_TypedError(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "test", AppSecret: "s", Brand: core.BrandFeishu}
-	cmd := &cobra.Command{Use: "test"}
-	cmd.Flags().String("start", "", "")
-	cmd.Flags().String("end", "", "")
-	_ = cmd.Flags().Set("start", "2026-03-25T00:00+08:00")
-	_ = cmd.Flags().Set("end", "2026-03-24T00:00+08:00")
-	runtime := common.TestNewRuntimeContext(cmd, cfg)
-
-	_, _, err := parseTimeRange(runtime)
-	if err == nil {
-		t.Fatal("expected error for start after end")
-	}
-	if !strings.Contains(err.Error(), "--start") || !strings.Contains(err.Error(), "--end") {
-		t.Errorf("message should mention --start and --end, got: %v", err)
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "--start" {
-		t.Errorf("Param = %q, want \"--start\"", ve.Param)
-	}
-}
-
-func TestSearch_Validation_QueryTooLong_TypedError(t *testing.T) {
-	cmd := &cobra.Command{Use: "test"}
-	cmd.Flags().String("query", "", "")
-	cmd.Flags().String("start", "", "")
-	cmd.Flags().String("end", "", "")
-	cmd.Flags().String("organizer-ids", "", "")
-	cmd.Flags().String("participant-ids", "", "")
-	cmd.Flags().String("room-ids", "", "")
-	cmd.Flags().String("page-size", "", "")
-	_ = cmd.Flags().Set("query", strings.Repeat("x", 51))
-
-	runtime := common.TestNewRuntimeContext(cmd, defaultConfig())
-	err := VCSearch.Validate(context.Background(), runtime)
-	if err == nil {
-		t.Fatal("expected validation error for overlong query")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-	if ve.Param != "--query" {
-		t.Errorf("Param = %q, want \"--query\"", ve.Param)
-	}
-}
-
-func TestSearch_Validation_NoFilter_TypedError(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
-	err := mountAndRun(t, VCSearch, []string{"+search", "--as", "user"}, f, nil)
-	if err == nil {
-		t.Fatal("expected validation error for no filter")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Errorf("Subtype = %q, want %q", ve.Subtype, errs.SubtypeInvalidArgument)
-	}
-}
-
-func TestBuildSearchParams(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "test", AppSecret: "s", Brand: core.BrandFeishu}
-
-	t.Run("defaults", func(t *testing.T) {
-		cmd := &cobra.Command{Use: "test"}
-		cmd.Flags().String("page-token", "", "")
-		cmd.Flags().String("page-size", "", "")
-		runtime := common.TestNewRuntimeContext(cmd, cfg)
-		params := buildSearchParams(runtime)
-		if params["page_size"] != "15" {
-			t.Errorf("page_size = %v, want \"15\"", params["page_size"])
-		}
-		if _, ok := params["page_token"]; ok {
-			t.Error("page_token should be absent when not set")
-		}
-	})
-
-	t.Run("custom page-size and page-token", func(t *testing.T) {
-		cmd := &cobra.Command{Use: "test"}
-		cmd.Flags().String("page-token", "", "")
-		cmd.Flags().String("page-size", "", "")
-		_ = cmd.Flags().Set("page-size", "20")
-		_ = cmd.Flags().Set("page-token", "tok123")
-		runtime := common.TestNewRuntimeContext(cmd, cfg)
-		params := buildSearchParams(runtime)
-		if params["page_size"] != "20" {
-			t.Errorf("page_size = %v, want \"20\"", params["page_size"])
-		}
-		if params["page_token"] != "tok123" {
-			t.Errorf("page_token = %v, want \"tok123\"", params["page_token"])
-		}
-	})
-
-	t.Run("values are scalars not slices", func(t *testing.T) {
-		cmd := &cobra.Command{Use: "test"}
-		cmd.Flags().String("page-token", "", "")
-		cmd.Flags().String("page-size", "", "")
-		_ = cmd.Flags().Set("page-size", "10")
-		_ = cmd.Flags().Set("page-token", "p")
-		runtime := common.TestNewRuntimeContext(cmd, cfg)
-		params := buildSearchParams(runtime)
-		if _, isSlice := params["page_size"].([]string); isSlice {
-			t.Error("page_size must be a scalar string, not []string")
-		}
-		if _, isSlice := params["page_token"].([]string); isSlice {
-			t.Error("page_token must be a scalar string, not []string")
-		}
-	})
-}

skill-template/domains/im.md

@@ -6,7 +6,6 @@
 - **Reaction**: An emoji reaction on a message.
 - **Flag**: A bookmark on a message or thread.
 - **Feed Shortcut**: A chat pinned to the current user's feed sidebar, identified by `feed_card_id` (an `oc_xxx` open_chat_id for CHAT type).
-- **Feed Group**: A tag that groups feed cards in the feed list, identified by `feed_group_id` (ofg_xxx). Members are feed cards, each identified by `feed_id` + `feed_type`. Two types: `normal` (members managed explicitly) and `rule` (members auto-derived from rules).
 
 ## Resource Relationships
 

skill-template/domains/wiki.md

@@ -6,7 +6,6 @@
 
 ## 快速决策
 
-- 用户要**整理 / 盘点 / 归类 / 重构知识库、个人文档库、文档库目录或 Wiki 节点结构**，或要生成整理方案、目标目录树、移动计划时，不要只使用 Wiki 节点 API。必须先阅读 [`../lark-drive/references/lark-drive-workflow-knowledge-organize.md`](../lark-drive/references/lark-drive-workflow-knowledge-organize.md)，该 workflow 负责 Drive / Wiki / 个人文档库的统一入口解析、资源盘点、分类计划、写前确认和结果验证。
 - 用户给的是知识库 URL（`.../wiki/<token>`），且后续要查成员/加成员/删成员：先调用 `lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'` 获取 `space_id`，后续成员接口统一使用 `space_id`。
 - 用户要**删除**知识空间（`wiki +delete-space`）但只给了名称或 URL：**不能**把名称 / URL 原样传给 `--space-id`，必须先解析出真实 `space_id`。解析方式：
   - URL（`.../wiki/<token>`）：`lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}' --format json`，读 `data.node.space_id`。
@@ -14,7 +13,6 @@
   - **关键安全约束**：无论精确还是模糊，**无论命中 1 条还是多条，发起删除前都必须把候选（`name` + `space_id` + `description` + `space_type`）列给用户，由用户明确选定一个 `space_id` 再执行**。不要因为"只命中一条"就自动执行删除。
   - 命中 0 条：停下来问用户是名称拼错了还是调用方无权限；**不要**自行改名字重试。
   - 用户明确选定后再执行 `lark-cli wiki +delete-space --space-id <ID> --yes`（高风险写操作，必须显式 `--yes`）。
-  - 反例：不要把 wiki URL / 名称直接当 `--space-id`（如 `--space-id "https://.../wiki/<wiki_token>"`）；务必先用 `wiki spaces get_node` 解析出 `data.node.space_id` 再传。
 - 用户要在知识库中创建新节点，优先使用 `lark-cli wiki +node-create`。
 - 用户说“给知识库添加成员/管理员”：先把目标解析成“用户 / 群 / 部门 / 应用”四类之一，再决定 `--member-type`，不要先调 `wiki +member-add` 再根据报错反推类型。
 - 用户说“部门 + bot”：这是已知不支持路径。不要继续尝试 `wiki +member-add --as bot`；直接提示必须改成 `--as user`，或明确告知当前要求无法完成。

skills/lark-doc/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: lark-doc
-version: 2.0.0
-description: "飞书云文档 / Docx / 知识库 Wiki 文档（v2）：创建、打开、读取、获取、查看、总结、整理、改写、翻译、审阅和编辑飞书文档内容。当用户给出飞书文档 URL/token，或说查看/读取/打开某个文档、提取文档内容、总结文档、生成/创建文档、追加/替换/删除/移动内容、调整排版、插入或下载文档图片/附件/素材/画板缩略图时使用。文档内容中出现嵌入电子表格、多维表格、需要将重要信息可视化为画板（含 SVG 画板）、引用或同步块时，也先用本 skill 读取和提取 token，再切到对应 skill 下钻。默认使用 DocxXML，也支持 Markdown。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"
+description: "飞书云文档 / Docx / 知识库 Wiki 文档（v2）：创建、打开、读取、获取、查看、总结、整理、改写、翻译、审阅和编辑飞书文档内容。当用户给出飞书文档 URL/token，或说查看/读取/打开某个文档、提取文档内容、总结文档、生成/创建文档、追加/替换/删除/移动内容、调整排版、插入或下载文档图片/附件/素材/画板缩略图时使用。文档内容中出现嵌入电子表格、多维表格、需要将重要信息可视化为画板（含 SVG 画板）、引用或同步块时，也先用本 skill 读取和提取 token，再切到对应 skill 下钻。使用本 skill 时，docs +create、docs +fetch、docs +update 必须携带 --api-version v2；默认使用 DocxXML，也支持 Markdown。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"
 metadata:
   requires:
     bins: ["lark-cli"]

skills/lark-doc/references/lark-doc-create.md

@@ -1,9 +1,10 @@
 # docs +create（创建飞书云文档）
 
 > **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
-> 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
-> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
-> 3. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
+> 1. [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) — 认证、全局参数和安全规则
+> 2. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
+> 3. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
+> 4. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
 >
 > **未读完以上文件就生成内容会导致格式错误或样式不达标。**
 
@@ -84,3 +85,4 @@ lark-cli docs +create --api-version v2 --doc-format markdown --content $'# 项
 - [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
 - [`lark-doc-update.md`](lark-doc-update.md) — 更新文档
 - [`lark-doc-media-insert.md`](lark-doc-media-insert.md) — 插入图片/文件到文档
+- [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-doc/references/lark-doc-fetch.md

@@ -1,6 +1,8 @@
 
 # docs +fetch（获取飞书云文档）
 
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
 ## 命令
 
 ```bash
@@ -134,4 +136,5 @@ lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
 - [lark-doc-create](lark-doc-create.md) — 创建文档
 - [lark-doc-update](lark-doc-update.md) — 更新文档
 - [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材
-- [lark-doc-media-download](lark-doc-media-download.md) — 下载素材/画板缩略图
+- [lark-doc-media-download](lark-doc-media-download.md) — 下载素材/画板缩略图
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-doc/references/lark-doc-md.md

@@ -69,7 +69,3 @@ Markdown 格式支持通过 URL 插入网络图片，图片将自动从 HTTP 下
 
 非原生 Markdown 语法的内容（如下划线、高亮框(Callout)、勾选框、多维表格、画板、思维导图、电子表格、网格布局、引用(@文档/@人)、按钮、日期提醒、行内文件、文字颜色/背景色、同步块等）采用 XML 语法表示，详见 [`lark-doc-xml.md`](lark-doc-xml.md)。
 > **⚠️ XML 标签会被解析并生效**：即使在 `--doc-format markdown` 下，`<b>`、`<u>`、`<img>` 等 XML 标签也会被识别为对应的富文本节点，**不会**按字面量显示。如需字面量输出尖括号包裹的文本（例如示例中的 `<tag>`），必须转义左尖括号：`\<b>`、`\<img>`。
-
-## 参考
-
-- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范

skills/lark-doc/references/lark-doc-update.md

@@ -2,9 +2,10 @@
 # docs +update（更新飞书云文档）
 
 > **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
-> 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
-> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
-> 3. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）
+> 1. [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) — 认证、全局参数和安全规则
+> 2. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
+> 3. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
+> 4. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）
 >
 > **未读完以上文件就生成内容会导致格式错误或样式不达标。**
 
@@ -248,3 +249,4 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
 - [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
 - [`lark-doc-create.md`](lark-doc-create.md) — 创建文档
 - [`lark-doc-media-insert.md`](lark-doc-media-insert.md) — 插入图片/文件到文档
+- [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-im/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-im
 version: 1.0.0
-description: "飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复、发送应用内/短信/电话加急。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶（添加/移除/查询置顶会话）、管理标签数据时使用。"
+description: "飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复、发送应用内/短信/电话加急。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶（添加/移除/查询置顶会话）时使用。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -20,7 +20,6 @@ metadata:
 - **Reaction**: An emoji reaction on a message.
 - **Flag**: A bookmark on a message or thread.
 - **Feed Shortcut**: A chat pinned to the current user's feed sidebar, identified by `feed_card_id` (an `oc_xxx` open_chat_id for CHAT type).
-- **Feed Group**: A tag that groups feed cards in the feed list, identified by `feed_group_id` (ofg_xxx). Members are feed cards, each identified by `feed_id` + `feed_type`. Two types: `normal` (members managed explicitly) and `rule` (members auto-derived from rules).
 
 ## Resource Relationships
 
@@ -97,15 +96,12 @@ Shortcut 是对常用操作的高级封装（`lark-cli im +<verb> [flags]`）。
 | [`+messages-search`](references/lark-im-messages-search.md) | Search messages across chats (supports keyword, sender, time range filters) with user identity; user-only; filters by chat/sender/attachment/time, supports auto-pagination via `--page-all` / `--page-limit`, enriches results via batched mget and chats batch_query |
 | [`+messages-send`](references/lark-im-messages-send.md) | Send a message to a chat or direct message; user/bot; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key |
 | [`+threads-messages-list`](references/lark-im-threads-messages-list.md) | List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination |
-| [`+flag-create`](references/lark-im-flag-create.md) | Create a bookmark on a message; user-only; defaults to message-layer flag; use --flag-type feed for feed-layer flag (item_type auto-detected from chat mode) |
-| [`+flag-cancel`](references/lark-im-flag-cancel.md) | Cancel (remove) a bookmark. When no --flag-type is given, best-effort double-cancel: removes message layer and (when chat_type is determinable) feed layer |
+| [`+flag-create`](references/lark-im-flag-create.md) | Create a bookmark on a message or thread; user-only; defaults to message-layer flag; feed-layer flag requires explicit --item-type + --flag-type |
+| [`+flag-cancel`](references/lark-im-flag-cancel.md) | Cancel (remove) a bookmark. When no --flag-type is given, checks if the message is a thread root message; if so, cancels both message and feed layers |
 | [`+flag-list`](references/lark-im-flag-list.md) | List bookmarks; user-only; auto-enriches feed-type thread entries with message content; supports `--page-all` auto-pagination |
 | [`+feed-shortcut-create`](references/lark-im-feed-shortcut-create.md) | Add chats to the user's feed shortcuts; user-only; oc_xxx chat IDs only; batch up to 10 per call; `--head`/`--tail` controls insertion order; partial failures return an `ok:false` ledger |
 | [`+feed-shortcut-remove`](references/lark-im-feed-shortcut-remove.md) | Remove chats from the user's feed shortcuts; user-only; batch up to 10 per call; removing an absent shortcut is idempotent success; real per-item failures return an `ok:false` ledger |
 | [`+feed-shortcut-list`](references/lark-im-feed-shortcut-list.md) | List one page of the user's feed shortcuts; user-only; omit `--page-token` for the first page; default output enriches CHAT entries under `detail`; pass `--no-detail` to skip the extra lookup and `im:chat:read` scope |
-| [`+feed-group-list`](references/lark-im-feed-group-list.md) | List the caller's feed groups (tags); user-only; supports `--page-all` auto-pagination |
-| [`+feed-group-list-item`](references/lark-im-feed-group-list-item.md) | List feed cards in a feed group (tag); user-only; enriches each item with chat_name resolved from feed_id; supports --page-all auto-pagination |
-| [`+feed-group-query-item`](references/lark-im-feed-group-query-item.md) | Look up specific feed cards in a feed group (tag) by ID; user-only; enriches each item with chat_name resolved from feed_id |
 
 ## API Resources
 
@@ -161,15 +157,6 @@ lark-cli im <resource> <method> [flags] # 调用 API
   - `delete` — 移除 Pin 消息。Identity: supports `user` and `bot`.
   - `list` — 获取群内 Pin 消息。Identity: supports `user` and `bot`.
 
-### feed.groups
-
-  - `batch_add_item` — Batch add feed cards to a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
-  - `batch_query` — Batch query feed groups. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
-  - `batch_remove_item` — Batch remove feed cards from a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
-  - `create` — Create a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
-  - `delete` — Delete a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
-  - `update` — Update a feed group. Identity: `user` only (`user_access_token`).[Must-read](references/lark-im-feed-groups.md)
-
 ## 权限表
 
 | 方法 | 所需 scope |
@@ -198,9 +185,3 @@ lark-cli im <resource> <method> [flags] # 调用 API
 | `pins.create` | `im:message.pins:write_only` |
 | `pins.delete` | `im:message.pins:write_only` |
 | `pins.list` | `im:message.pins:read` |
-| `feed.groups.batch_add_item` | `im:feed_group_v1:write` |
-| `feed.groups.batch_query` | `im:feed_group_v1:read` |
-| `feed.groups.batch_remove_item` | `im:feed_group_v1:write` |
-| `feed.groups.create` | `im:feed_group_v1:write` |
-| `feed.groups.delete` | `im:feed_group_v1:write` |
-| `feed.groups.update` | `im:feed_group_v1:write` |

skills/lark-im/references/lark-im-feed-group-list-item.md

@@ -1,68 +0,0 @@
-# +feed-group-list-item
-
-> Shortcut for `lark-cli im +feed-group-list-item`. List the feed cards inside one feed group (tag), enriched with a readable `chat_name`.
-
-`+feed-group-list-item` is the only CLI surface for the `feed.groups.list_item` read API — there is no raw `feed.groups list_item` command. It resolves a human-readable `chat_name` for every feed card it returns: a v1 feed card's `feed_id` is always a chat ID (`oc_xxx`), so the shortcut issues a follow-up `POST /open-apis/im/v1/chats/batch_query` and injects `chat_name` into each entry of both `items[]` and `deleted_items[]`.
-
-## Identity
-
-User-only. Run with `--as user`.
-
-## Scopes
-
-Because chat-name resolution always runs, this shortcut needs **two** user scopes unconditionally:
-
-- `im:feed_group_v1:read` — to read the items
-- `im:chat:read` — to resolve names
-
-`chat_name` resolution always runs, so there is no single-scope, un-enriched path. For the other raw `feed.groups.*` methods, see [lark-im-feed-groups.md](lark-im-feed-groups.md).
-
-## Usage
-
-```bash
-# First page, enriched with chat names
-lark-cli im +feed-group-list-item --as user --feed-group-id ofg_xxx
-
-# Auto-paginate through everything within a time window
-lark-cli im +feed-group-list-item --as user --feed-group-id ofg_xxx \
-  --page-all --start-time 1767196800000 --end-time 1767200000000
-```
-
-## Flags
-
-| Flag | Required | Description |
-|---|---|---|
-| `--feed-group-id` | Yes | Feed group ID (`ofg_xxx`); path parameter |
-| `--page-size` | No | Records per page, 1–50 (default 50) |
-| `--page-token` | No | Continuation token for a specific page |
-| `--page-all` | No | Auto-paginate and merge all pages |
-| `--page-limit` | No | Max pages when `--page-all` is set, 1–1000 (default 20) |
-| `--start-time` | No | Update-time window start (Unix milliseconds as a decimal string) |
-| `--end-time` | No | Update-time window end (Unix milliseconds as a decimal string) |
-
-When `--page-token` is set explicitly, it wins over `--page-all` (you get exactly that page).
-
-## Output
-
-JSON keeps the raw envelope and adds `chat_name` to each resolvable item:
-
-```json
-{
-  "items": [
-    { "feed_id": "oc_abc", "feed_type": "chat", "update_time": "1767196800000", "chat_name": "Release Team" }
-  ],
-  "deleted_items": [
-    { "feed_id": "oc_def", "feed_type": "chat", "update_time": "1767196800000", "chat_name": "Old Channel" }
-  ],
-  "page_token": "",
-  "has_more": false
-}
-```
-
-A feed card whose chat cannot be resolved (soft-deleted or no permission) simply omits `chat_name` — the command still exits 0. p2p (direct) chats also omit `chat_name`: the server returns an empty `name` for them (the client UI shows the partner's display name instead); if a label is needed, fetch the chat via `chats/batch_query`, read `p2p_target_id`, and resolve it with a contact lookup.
-
-## See also
-
-- [lark-im-feed-groups.md](lark-im-feed-groups.md) — raw `feed.groups.*` APIs, enums, and rule guidance
-- [lark-im-feed-group-list.md](lark-im-feed-group-list.md) — list your feed groups
-- [lark-im-feed-group-query-item.md](lark-im-feed-group-query-item.md) — look up specific feed cards by ID

skills/lark-im/references/lark-im-feed-group-list.md

@@ -1,65 +0,0 @@
-# +feed-group-list
-
-> Shortcut for `lark-cli im +feed-group-list`. List the caller's feed groups (tags) with auto-pagination that correctly merges both the live and soft-deleted lists.
-
-`+feed-group-list` is the only CLI surface for listing feed groups — there is no raw `feed.groups list` command. The list response carries two parallel arrays — `groups` (live) and `deleted_groups` (soft-deleted). The shortcut paginates this dual-list response correctly: its `--page-all` merges **both** arrays across pages (a naive single-array pager would silently drop one list's later pages). It adds no enrichment.
-
-## Identity
-
-User-only. Run with `--as user`.
-
-## Scopes
-
-- `im:feed_group_v1:read`
-
-## Usage
-
-```bash
-# First page
-lark-cli im +feed-group-list --as user
-
-# Auto-paginate through all your feed groups (both live and deleted)
-lark-cli im +feed-group-list --as user --page-all
-
-# Within an update-time window
-lark-cli im +feed-group-list --as user --page-all \
-  --start-time 1767196800000 --end-time 1767200000000
-```
-
-## Flags
-
-| Flag | Required | Description |
-|---|---|---|
-| `--page-size` | No | Records per page, 1–50 (default 50). Caps the combined `groups` + `deleted_groups` count, so a page may hold fewer live groups than the size suggests |
-| `--page-token` | No | Continuation token for a specific page |
-| `--page-all` | No | Auto-paginate and merge all pages (both lists) |
-| `--page-limit` | No | Max pages when `--page-all` is set, 1–1000 (default 20) |
-| `--start-time` | No | Update-time window start (Unix milliseconds as a decimal string) |
-| `--end-time` | No | Update-time window end (Unix milliseconds as a decimal string) |
-
-When `--page-token` is set explicitly, it wins over `--page-all` (you get exactly that page).
-
-## Output
-
-JSON keeps the raw envelope; with `--page-all` both lists are returned fully merged:
-
-```json
-{
-  "groups": [
-    { "group_id": "ofg_xxx", "type": "normal", "name": "Releases", "rules": { "rules": [] } }
-  ],
-  "deleted_groups": [
-    { "group_id": "ofg_yyy", "type": "rule", "name": "Old", "rules": { "rules": [] } }
-  ],
-  "page_token": "",
-  "has_more": false
-}
-```
-
-> `page_size` counts live and deleted groups together, and the per-page count can be smaller still when entries are filtered — so never infer completeness from counts. Pagination is governed solely by `has_more`.
-
-## See also
-
-- [lark-im-feed-groups.md](lark-im-feed-groups.md) — raw `feed.groups.*` APIs, enums, and rule guidance
-- [lark-im-feed-group-list-item.md](lark-im-feed-group-list-item.md) — list the feed cards inside one group
-- [lark-im-feed-group-query-item.md](lark-im-feed-group-query-item.md) — look up specific feed cards by ID

skills/lark-im/references/lark-im-feed-group-query-item.md

@@ -1,44 +0,0 @@
-# +feed-group-query-item
-
-> Shortcut for `lark-cli im +feed-group-query-item`. Look up specific feed cards inside one feed group (tag) by ID, enriched with a readable `chat_name`.
-
-`+feed-group-query-item` is the only CLI surface for the `feed.groups.batch_query_item` read API — there is no raw `feed.groups batch_query_item` command. It resolves a human-readable `chat_name` for every feed card it returns: a v1 feed card's `feed_id` is always a chat ID (`oc_xxx`), so the shortcut issues a follow-up `POST /open-apis/im/v1/chats/batch_query` and injects `chat_name` into each entry of both `items[]` and `deleted_items[]`.
-
-## Identity
-
-User-only. Run with `--as user`.
-
-## Scopes
-
-Because chat-name resolution always runs, this shortcut needs **two** user scopes unconditionally:
-
-- `im:feed_group_v1:read` — to read the items
-- `im:chat:read` — to resolve names
-
-`chat_name` resolution always runs, so there is no single-scope, un-enriched path. For the other raw `feed.groups.*` methods, see [lark-im-feed-groups.md](lark-im-feed-groups.md).
-
-## Usage
-
-```bash
-lark-cli im +feed-group-query-item --as user \
-  --feed-group-id ofg_xxx --feed-id oc_a,oc_b
-```
-
-## Flags
-
-| Flag | Required | Description |
-|---|---|---|
-| `--feed-group-id` | Yes | Feed group ID (`ofg_xxx`); path parameter |
-| `--feed-id` | Yes | Comma-separated chat IDs (`oc_xxx`); `feed_type` is fixed to `chat` |
-
-## Output
-
-The command sends `{"items":[{"feed_id":"oc_a","feed_type":"chat"},{"feed_id":"oc_b","feed_type":"chat"}]}`, then enriches the response (`items[]` and `deleted_items[]`) with `chat_name` exactly as `+feed-group-list-item` does. There is no pagination for this method.
-
-A feed card whose chat cannot be resolved (soft-deleted or no permission) simply omits `chat_name` — the command still exits 0. p2p (direct) chats also omit `chat_name`: the server returns an empty `name` for them (the client UI shows the partner's display name instead); if a label is needed, fetch the chat via `chats/batch_query`, read `p2p_target_id`, and resolve it with a contact lookup.
-
-## See also
-
-- [lark-im-feed-groups.md](lark-im-feed-groups.md) — raw `feed.groups.*` APIs, enums, and rule guidance
-- [lark-im-feed-group-list.md](lark-im-feed-group-list.md) — list your feed groups
-- [lark-im-feed-group-list-item.md](lark-im-feed-group-list-item.md) — list all feed cards in a group (paginated)

skills/lark-im/references/lark-im-feed-groups.md

@@ -1,452 +0,0 @@
-# im feed.groups
-
-> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
-
-This reference is the shared annotation target for the IM feed-group (tag) APIs: it documents what each method does, the `--params` / `--data` request and response shapes, and the enum surface used in payloads. The full method list is in [Command Overview](#command-overview) below.
-
-> **Important:** The six raw commands (`create`, `update`, `delete`, `batch_query`, `batch_add_item`, `batch_remove_item`) take structured input through `--params '<json>'` and `--data '<json>'` rather than typed flags. The three read methods (`list`, `list_item`, `batch_query_item`) are exposed only as typed `+` shortcut wrappers — see [Shortcuts](#shortcuts). All methods are user-only; see [Common Notes](#common-notes).
-
-> **Picking a read method:** `batch_query` / `+feed-group-query-item` are lightweight ID lookups; `+feed-group-list` / `+feed-group-list-item` paginate the whole set and are much heavier. When you already hold the IDs (`group_id` from `create`, the `feed_id`s you passed to `batch_add_item`), prefer the lightweight lookup. Reserve the list methods for when you actually need to discover IDs you don't have.
-
-## Command Overview
-
-| Method | Purpose |
-|---|---|
-| `feed.groups.create` | Create a new feed group (tag) |
-| `feed.groups.update` | Update a feed group's name and/or rules |
-| `feed.groups.delete` | Delete one feed group |
-| `feed.groups.batch_query` | Look up feed groups by ID list |
-| `feed.groups.list` | List the caller's feed groups with optional time-range filter — **CLI: only via `+feed-group-list` shortcut** |
-| `feed.groups.batch_add_item` | Add feed cards (chats) into a feed group |
-| `feed.groups.batch_remove_item` | Remove feed cards from a feed group |
-| `feed.groups.batch_query_item` | Look up feed cards inside a group by ID list — **CLI: only via `+feed-group-query-item` shortcut** |
-| `feed.groups.list_item` | List feed cards inside one feed group — **CLI: only via `+feed-group-list-item` shortcut** |
-
-> HTTP method and path are not duplicated here. For the six raw methods, inspect them with `lark-cli schema im.feed.groups.<method>` when needed; the three shortcut-only read methods (`list`, `list_item`, `batch_query_item`) use typed flags (see their `--help`).
-
-## Shortcuts
-
-Three typed `+` shortcuts cover the feed-group read paths. All are user-only.
-
-| Shortcut | Purpose | Notes |
-|---|---|---|
-| [`+feed-group-list`](lark-im-feed-group-list.md) | List your feed groups | Its `--page-all` correctly merges the live and soft-deleted lists. No enrichment |
-| [`+feed-group-list-item`](lark-im-feed-group-list-item.md) | List the feed cards inside a group | Enriches each card with `chat_name` |
-| [`+feed-group-query-item`](lark-im-feed-group-query-item.md) | Look up feed cards in a group by ID | Enriches each card with `chat_name` |
-
-The two `*-item` shortcuts resolve `chat_name` via a follow-up `chats/batch_query`, so they need `im:chat:read` in addition to `im:feed_group_v1:read`; `+feed-group-list` needs only `im:feed_group_v1:read`. All three are the **only** CLI surface for their methods — `list`, `list_item`, and `batch_query_item` have no raw command; full flags and response shapes live in the shortcut docs linked above.
-
-## Common Notes
-
-- `feed_group_id` is the feed-group identifier returned by `create`, typically formatted as `ofg_xxx`. It is an opaque string — the group's stable ID.
-- `feed_id` is the identifier of one feed card inside a group. In v1 only the `chat` feed card type is supported (see `feed_card_type` below), so `feed_id` is currently a chat ID such as `oc_xxx`.
-- All `feed.groups.*` methods require `user_access_token`. Run with `--as user`; bot/tenant tokens are rejected.
-- Read APIs (`batch_query`, `list`, `batch_query_item`, `list_item`) return **two parallel lists**: a live list (`groups[]` or `items[]`) and a soft-deleted list (`deleted_groups[]` or `deleted_items[]`). Consumers tracking incremental sync should consume both.
-- Time-range fields (`start_time`, `end_time`, `update_time`) are Unix timestamps **in milliseconds**, encoded as decimal strings (e.g. `1767196800000`).
-- Rule-based feed groups (`type=rule`) auto-populate from the rules declared in `feed_group_creator.rules`. Normal feed groups (`type=normal`) are managed explicitly via `batch_add_item` / `batch_remove_item`.
-
-> **Choose the simplest group that fits** — it keeps `create` / `update` fast and predictable. Apply these in order:
-> 1. **Prefer `type=normal`.** When the target chats are known up front, set membership explicitly with `batch_add_item` / `batch_remove_item`. Use `type=rule` only when membership must be derived automatically.
-> 2. **Keep the rule set smallest.** Use the fewest `rules[]` and `condition_items[]` that express the intent (one condition is ideal). This outranks the style rules below — never split a rule or add conditions just to satisfy them (e.g. one `match_any` rule beats two single-condition rules for "A or B").
-> 3. **Within that, make each condition precise.** Prefer positive, specific conditions (`is`, or `contain` with a distinctive keyword) over exclusion (`is_not`, `not_contain`) or broad keywords, which capture more than intended. For a multi-condition rule, prefer `match_all` (narrower) over `match_any` (wider).
-
-## Inspect Schema
-
-```bash
-lark-cli schema im.feed.groups
-lark-cli schema im.feed.groups.create --format pretty
-lark-cli schema im.feed.groups.batch_add_item --format pretty
-```
-
-> `list`, `list_item`, and `batch_query_item` have no raw method schema (they are shortcut-only). Inspect their flags with `lark-cli im +feed-group-list --help` / `+feed-group-list-item --help` / `+feed-group-query-item --help` instead.
-
-## create
-
-Create a new feed group. Returns the new `group_id` on success.
-
-> **Prefer `type=normal`.** Use `type=rule` only when membership must be derived automatically, and keep the rule set small and precise — see the guidance under [Common Notes](#common-notes).
-
-```bash
-# Normal (empty) group
-lark-cli im feed.groups create --as user \
-  --data '{"feed_group_creator":{"type":"normal","name":"Releases"}}'
-
-# Rule-based group: auto-add p2p chats with "release" in their name
-lark-cli im feed.groups create --as user \
-  --data '{
-    "feed_group_creator":{
-      "type":"rule",
-      "name":"Auto: release chats",
-      "rules":{
-        "rules":[
-          {
-            "condition":{
-              "match_type":"match_all",
-              "condition_items":[
-                {"type":"chat_type","operator":"is","chat_type":"p2p"},
-                {"type":"keyword","operator":"contain","keyword":"release"}
-              ]
-            },
-            "action":"add"
-          }
-        ]
-      }
-    }
-  }'
-```
-
-### Request
-
-#### `--params`
-
-| Parameter | Required | Description |
-|---|---|---|
-| `user_id_type` | No | ID type used when the request body contains `user_id` references inside rules. One of `open_id`, `union_id`, `user_id` |
-
-#### `--data`
-
-| Field | Required | Description |
-|---|---|---|
-| `feed_group_creator.type` | Yes | `normal` (empty group) or `rule` (auto-populated by rules) |
-| `feed_group_creator.name` | Yes | Display name, e.g. `"标签名称测试"` |
-| `feed_group_creator.rules` | No | Rule object (required when `type=rule`). See `feed_group_rules` section below |
-
-### Response
-
-```json
-{
-  "group_id": "ofg_xxx"
-}
-```
-
-## update
-
-Update a feed group's name and/or rules. The `update_fields` array tells the server which fields are being updated.
-
-> **Scope each update to what actually changed.** If you only need to rename, pass `update_fields:[1]` so the rules are left untouched. When you do change rules, the same guidance under [Common Notes](#common-notes) applies to the resulting set.
-
-```bash
-# Rename only
-lark-cli im feed.groups update --as user \
-  --params '{"feed_group_id":"ofg_xxx"}' \
-  --data '{"feed_group_updater":{"name":"测试标签名称","update_fields":[1]}}'
-
-# Replace rules only (rules array uses the feed_group_rules shape — see that section)
-lark-cli im feed.groups update --as user \
-  --params '{"feed_group_id":"ofg_xxx"}' \
-  --data '{
-    "feed_group_updater":{
-      "rules":{"rules":[]},
-      "update_fields":[2]
-    }
-  }'
-```
-
-### Request
-
-#### `--params`
-
-| Parameter | Required | Description |
-|---|---|---|
-| `feed_group_id` | Yes | Path parameter — the feed group to update |
-| `user_id_type` | No | ID type for any `user_id` fields inside `rules` |
-
-#### `--data`
-
-| Field | Required | Description |
-|---|---|---|
-| `feed_group_updater.name` | No | New display name |
-| `feed_group_updater.rules` | No | Replacement rule object. Same structure as `create.feed_group_creator.rules` |
-| `feed_group_updater.update_fields` | No | Array of integer update markers: `1` = name, `2` = rules. Server applies only the listed fields |
-
-### Response
-
-Empty body on success. Inspect the CLI exit code for status.
-
-## delete
-
-Delete one feed group.
-
-```bash
-lark-cli im feed.groups delete --as user \
-  --params '{"feed_group_id":"ofg_xxx"}'
-```
-
-### Request
-
-| Parameter | Required | Description |
-|---|---|---|
-| `feed_group_id` | Yes | Path parameter — the feed group to delete |
-
-### Response
-
-Empty body on success.
-
-## batch_query
-
-Look up feed groups by an explicit list of IDs. Returns both live and soft-deleted matches.
-
-```bash
-lark-cli im feed.groups batch_query --as user \
-  --params '{"user_id_type":"open_id"}' \
-  --data '{"group_ids":["ofg_xxx","ofg_yyy"]}'
-```
-
-### Request
-
-#### `--params`
-
-| Parameter | Required | Description |
-|---|---|---|
-| `user_id_type` | No | ID type used when the response includes `user_id` references inside `groups[].rules` |
-
-#### `--data`
-
-| Field | Required | Description |
-|---|---|---|
-| `group_ids` | Yes | Array of feed group IDs to look up |
-
-### Response
-
-```json
-{
-  "groups": [
-    {
-      "group_id": "ofg_xxx",
-      "type": "normal",
-      "name": "test",
-      "rules": { "rules": [] }
-    }
-  ],
-  "deleted_groups": [
-    {
-      "group_id": "ofg_yyy",
-      "type": "rule",
-      "name": "test",
-      "rules": { "rules": [] }
-    }
-  ]
-}
-```
-
-Each `rules.rules[]` element follows the `feed_group_rules` shape — see that section for the full structure.
-
-### Top-Level Fields
-
-| Field | Type | Meaning |
-|---|---|---|
-| `groups` | `array<object>` | Live feed groups for the requested IDs |
-| `deleted_groups` | `array<object>` | Soft-deleted matches, returned for incremental-sync clients |
-
-Each element carries `group_id`, `type`, `name`, and (when defined) `rules`.
-
-## list
-
-Shortcut-only: [`+feed-group-list`](lark-im-feed-group-list.md). Lists the caller's feed groups, optionally filtered by an update-time window. Its `--page-all` correctly merges the live (`groups`) and soft-deleted (`deleted_groups`) lists across pages. There is no raw command — flags and response shape are in the linked shortcut doc.
-
-## batch_add_item
-
-Add feed cards (chats) into one feed group. Partial failures are reported in `failed_items`.
-
-```bash
-lark-cli im feed.groups batch_add_item --as user \
-  --params '{"feed_group_id":"ofg_xxx"}' \
-  --data '{
-    "items":[
-      {"feed_id":"oc_xxx","feed_type":"chat"},
-      {"feed_id":"oc_yyy","feed_type":"chat"}
-    ]
-  }'
-```
-
-### Request
-
-| Source | Field | Required | Description |
-|---|---|---|---|
-| `--params` | `feed_group_id` | Yes | Path parameter — the target feed group |
-| `--data` | `items[]` | Yes | Array of feed cards to add |
-| `--data` | `items[].feed_id` | No | The chat ID to add (e.g. `oc_xxx`) |
-| `--data` | `items[].feed_type` | Yes (`"chat"` only) | Wire-typed as an open string. v1 OAPI service accepts only `chat`; anything else is rejected at runtime. See the Enums section. |
-
-> Note: `items[].feed_id` is not marked as required in the API schema, but every element of `items` must set it — a missing field yields an unusable entry. Always pass `{"feed_id": "oc_xxx", "feed_type": "chat"}` per item.
-
-### Response
-
-```json
-{
-  "failed_items": [
-    {
-      "item": { "feed_id": "oc_xxx", "feed_type": "chat" },
-      "error_code": 240001,
-      "error_message": "feed_id is invalid"
-    }
-  ]
-}
-```
-
-| Field | Type | Meaning |
-|---|---|---|
-| `failed_items` | `array<object>` | Items that failed; absent or empty means all succeeded |
-| `failed_items[].item` | `object` | The original `{feed_id, feed_type}` element |
-| `failed_items[].error_code` | `integer` | Numeric error code |
-| `failed_items[].error_message` | `string` | Human-readable failure reason |
-
-## batch_remove_item
-
-Remove feed cards from one feed group. Same request and response shape as `batch_add_item`.
-
-```bash
-lark-cli im feed.groups batch_remove_item --as user \
-  --params '{"feed_group_id":"ofg_xxx"}' \
-  --data '{
-    "items":[
-      {"feed_id":"oc_xxx","feed_type":"chat"}
-    ]
-  }'
-```
-
-### Request
-
-| Source | Field | Required | Description |
-|---|---|---|---|
-| `--params` | `feed_group_id` | Yes | Path parameter — the target feed group |
-| `--data` | `items[]` | Yes | Array of feed cards to remove |
-| `--data` | `items[].feed_id` | No | The chat ID to remove |
-| `--data` | `items[].feed_type` | Yes (`"chat"` only) | Wire-typed as an open string. v1 OAPI service accepts only `chat`; anything else is rejected at runtime. See the Enums section. |
-
-> Note: same caveat as `batch_add_item` — `items[].feed_id` is optional per the API schema but must be present in practice.
-
-### Response
-
-Identical shape to `batch_add_item` — `failed_items[]` lists rows that did not remove cleanly.
-
-## batch_query_item
-
-Shortcut-only: [`+feed-group-query-item`](lark-im-feed-group-query-item.md). Looks up feed cards in a group by an explicit ID list and enriches each with `chat_name`. There is no raw command — flags and response shape are in the linked shortcut doc.
-
-## list_item
-
-Shortcut-only: [`+feed-group-list-item`](lark-im-feed-group-list-item.md). Lists the feed cards inside a group (paginated, `--page-all` supported) and enriches each with `chat_name`. There is no raw command — flags and response shape are in the linked shortcut doc.
-
-## Enums
-
-All enum values listed here are exhaustive.
-
-### `feed_group_type`
-
-Used in `feed_group_creator.type` and the response `groups[].type`.
-
-- `normal` — empty group; members managed explicitly via `batch_add_item` / `batch_remove_item`.
-- `rule` — auto-populated; `feed_group_creator.rules` must be supplied.
-
-### `feed_card_type`
-
-Used in `items[].feed_type` everywhere a feed card appears. Wire type is an open string.
-
-- `chat` — the only value the v1 OAPI service accepts. `feed_id` is therefore a chat ID such as `oc_xxx`.
-
-The CLI does not pre-validate this field — passing anything other than `chat` reaches the server and is rejected at runtime. Treat `chat` as effectively required.
-
-### `feed_group_rule_action`
-
-Used inside `feed_group_rules.rules[].action`.
-
-- `add` — when the condition matches, add the matching feed into this group.
-- `remove` — when the condition matches, remove the matching feed from this group.
-
-### `feed_group_rule_cond_match_type`
-
-Used inside `feed_group_rules.rules[].condition.match_type`.
-
-- `match_all` — every condition item must match.
-- `match_any` — at least one condition item must match.
-
-### `feed_group_rule_cond_item_type`
-
-Used inside `feed_group_rules.rules[].condition.condition_items[].type`. Determines which sibling field of the item is consulted.
-
-- `keyword` — match against a keyword; consult the `keyword` field.
-- `chatter` — match against a user; consult the `user_id` field (interpreted per the request's `user_id_type`).
-- `chat_type` — match against a chat type; consult the `chat_type` field.
-
-### `feed_group_rule_cond_item_operator`
-
-Used inside `feed_group_rules.rules[].condition.condition_items[].operator`. Typically paired with the relevant `type`:
-
-- `contain` — substring match; typically paired with `keyword`.
-- `not_contain` — substring non-match; typically paired with `keyword`.
-- `is` — equality; typically paired with `chatter` or `chat_type`.
-- `is_not` — non-equality; typically paired with `chatter` or `chat_type`.
-
-### `feed_group_rule_cond_item_chat_type`
-
-Used inside `feed_group_rules.rules[].condition.condition_items[].chat_type` when `type=chat_type`.
-
-- `p2p`
-- `group`
-- `thread_group`
-- `helpdesk`
-- `bot`
-- `mute`
-- `flag`
-- `cross_tenant`
-- `any`
-
-### `update_fields`
-
-Used inside `feed_group_updater.update_fields`. Multiple values may be listed.
-
-- `1` — update name only.
-- `2` — update rules only.
-
-Wire form: integers (`1` = name, `2` = rules). The server rejects the lowercase string forms (`"name"`, `"rules"`) with `9499 Invalid parameter value`. Omit the array (or pass an empty array) to make no field updates.
-
-## feed_group_rules
-
-The same nested object is used in `feed_group_creator.rules` (create), `feed_group_updater.rules` (update), and in read responses under `groups[].rules`. Shape:
-
-```json
-{
-  "rules": [
-    {
-      "condition": {
-        "match_type": "match_all",
-        "condition_items": [
-          { "type": "chat_type", "operator": "is", "chat_type": "group" },
-          { "type": "keyword",   "operator": "contain", "keyword": "release" }
-        ]
-      },
-      "action": "add"
-    }
-  ]
-}
-```
-
-Per-`type` required-field legend:
-
-- `type=keyword` → `keyword` is required; `user_id` and `chat_type` are ignored.
-- `type=chatter` → `user_id` is required; the request's `user_id_type` query parameter tells the server how to interpret it.
-- `type=chat_type` → `chat_type` is required.
-
-## Permissions
-
-| Method | Scope |
-|---|---|
-| `feed.groups.create` | `im:feed_group_v1:write` |
-| `feed.groups.update` | `im:feed_group_v1:write` |
-| `feed.groups.delete` | `im:feed_group_v1:write` |
-| `feed.groups.batch_query` | `im:feed_group_v1:read` |
-| `feed.groups.batch_add_item` | `im:feed_group_v1:write` |
-| `feed.groups.batch_remove_item` | `im:feed_group_v1:write` |
-
-The three read methods are shortcut-only:
-
-- [`+feed-group-list`](lark-im-feed-group-list.md) — `im:feed_group_v1:read`
-- [`+feed-group-list-item`](lark-im-feed-group-list-item.md) / [`+feed-group-query-item`](lark-im-feed-group-query-item.md) — `im:feed_group_v1:read` **plus** `im:chat:read` (they always resolve `chat_name`)
-
-If a required scope is missing, the CLI surfaces a hint such as `lark-cli auth login --scope "im:feed_group_v1:write"`.
-
-## References
-
-- [lark-im](../SKILL.md) — all IM commands
-- [lark-shared](../../lark-shared/SKILL.md) — authentication and global parameters

skills/lark-im/references/lark-im-flag-cancel.md

@@ -10,7 +10,7 @@ A message can have flags on both layers simultaneously:
 - Message layer: `(default, message)`
 - Feed layer: `(thread, feed)` or `(msg_thread, feed)` depending on chat type
 
-**When no `--flag-type` is specified, the shortcut performs best-effort double-cancel**: the message-layer flag is always removed; the feed-layer flag is also removed when the chat type can be determined (otherwise a warning is printed on stderr and the feed layer is skipped). The server handles cancel requests for non-existent flags idempotently, so this is safe.
+**When no `--flag-type` is specified, the shortcut performs double-cancel**: removes both message layer and feed layer flags. The server handles cancel requests for non-existent flags idempotently, so this is safe.
 
 **Feed layer item_type is determined by chat_mode**:
 - Topic-style chat (`chat_mode=topic`) → `item_type=thread`
@@ -37,7 +37,7 @@ lark-cli im +flag-cancel --as user --message-id om_xxx --dry-run
 | Parameter | Required | Description |
 |------|------|------|
 | `--message-id <om_xxx>` | Required | Message ID |
-| `--flag-type <name>` | No | `message` or `feed`; **when omitted, best-effort double-cancel of both layers** |
+| `--flag-type <name>` | No | `message` or `feed`; **when omitted, double-cancels both layers** |
 | `--item-type <name>` | No | `default\|thread\|msg_thread`; required when `--flag-type feed` |
 | `--as user` | Required | Currently only supports user identity |
 

skills/lark-shared/SKILL.md

@@ -126,7 +126,6 @@ lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 `_
 - **禁止输出密钥**（appSecret、accessToken）到终端明文。
 - **写入/删除操作前必须确认用户意图**。
 - 用 `--dry-run` 预览危险请求。
-- **文件路径只接受相对路径**：`--file`、`--output`、`--output-dir`、`@file` 等路径参数只接受 cwd 下的相对路径，传绝对路径会报 `unsafe file path`。数据输入（`@file`、大 JSON）优先用 stdin 传入，避免路径和转义问题。
 
 ## 高风险操作的审批协议（exit 10）
 

skills/lark-slides/SKILL.md

@@ -21,7 +21,6 @@ metadata:
 | 上传或使用图片 | 先上传为 `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` |
 
@@ -84,7 +83,6 @@ lark-cli auth login --domain slides
 - 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.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/xml-schema-quick-ref.md

@@ -142,8 +142,6 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 <icon iconType="iconpark/Base/setting.svg" topLeftX="80" topLeftY="120" width="32" height="32"/>
 ```
 
-`iconType` 必须来自已验证的 IconPark 路径。需要语义图标时，先运行 `scripts/iconpark_tool.py search --query "<语义>"`，不要凭记忆拼路径。更多规则见 [iconpark.md](iconpark.md)。
-
 ### whiteboard
 
 ```xml

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,177 +0,0 @@
-# Copyright (c) 2026 Lark Technologies Pte. Ltd.
-# SPDX-License-Identifier: MIT
-from __future__ import annotations
-
-import json
-import subprocess
-import sys
-import unittest
-from pathlib import Path
-
-import iconpark_tool
-
-
-SCRIPT_PATH = Path(__file__).resolve().with_name("iconpark_tool.py")
-
-
-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": 10})
-                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_keeps_high_value_top_results(self) -> None:
-        cases = [
-            ("安全", "iconpark/Safe/protect.svg"),
-            ("邮件", "iconpark/Office/mail-open.svg"),
-            ("会议", "iconpark/Office/schedule.svg"),
-            ("增长趋势", "iconpark/Charts/chart-line.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": 3})
-                self.assertTrue(results)
-                self.assertEqual(results[0]["iconType"], icon_type)
-
-    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))
-
-
-class IconParkToolCLITest(unittest.TestCase):
-    def run_tool(self, *args: str) -> subprocess.CompletedProcess[str]:
-        return subprocess.run(
-            [sys.executable, str(SCRIPT_PATH), *args],
-            capture_output=True,
-            check=False,
-            text=True,
-        )
-
-    def test_cli_search_writes_json_to_stdout(self) -> None:
-        result = self.run_tool("search", "--query", "增长趋势", "--limit", "5")
-        self.assertEqual(result.returncode, 0, result.stderr)
-        self.assertEqual(result.stderr, "")
-
-        output = json.loads(result.stdout)
-        self.assertTrue(output)
-        self.assertTrue(
-            any(entry["iconType"] == "iconpark/Charts/positive-dynamics.svg" for entry in output)
-        )
-
-    def test_cli_resolve_writes_json_to_stdout(self) -> None:
-        result = self.run_tool("resolve", "--name", "chart-line")
-        self.assertEqual(result.returncode, 0, result.stderr)
-        self.assertEqual(result.stderr, "")
-
-        output = json.loads(result.stdout)
-        self.assertEqual(output["iconType"], "iconpark/Charts/chart-line.svg")
-
-    def test_cli_list_categories_writes_json_to_stdout(self) -> None:
-        result = self.run_tool("list-categories")
-        self.assertEqual(result.returncode, 0, result.stderr)
-        self.assertEqual(result.stderr, "")
-
-        output = json.loads(result.stdout)
-        self.assertTrue(any(entry["category"] == "Charts" and entry["count"] > 0 for entry in output))
-
-    def test_cli_help_writes_usage_to_stderr(self) -> None:
-        result = self.run_tool("--help")
-        self.assertEqual(result.returncode, 0, result.stderr)
-        self.assertEqual(result.stdout, "")
-        self.assertIn("Usage:", result.stderr)
-        self.assertIn("python3 iconpark_tool.py search", result.stderr)
-
-    def test_cli_invalid_argument_writes_error_to_stderr(self) -> None:
-        result = self.run_tool("search", "增长趋势")
-        self.assertEqual(result.returncode, 1)
-        self.assertEqual(result.stdout, "")
-        self.assertIn("iconpark-tool error: unexpected argument: 增长趋势", result.stderr)
-
-    def test_cli_unknown_command_writes_usage_and_error_to_stderr(self) -> None:
-        result = self.run_tool("unknown")
-        self.assertEqual(result.returncode, 1)
-        self.assertEqual(result.stdout, "")
-        self.assertIn("Usage:", result.stderr)
-        self.assertIn("iconpark-tool error: unknown command: unknown", result.stderr)
-
-
-if __name__ == "__main__":
-    unittest.main()

skills/lark-wiki/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-wiki
-version: 1.0.1
-description: "飞书知识库：管理知识空间、空间成员和文档节点。创建和查询知识空间、查看和管理空间成员、管理节点层级结构、在知识库中组织文档和快捷方式。当用户需要在知识库中查找或创建文档、浏览知识空间结构、查看或管理空间成员、移动或复制节点时使用。当用户给出 doubao.com 的 /wiki/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：上传文件到知识库节点下（走 lark-drive）、编辑文档/表格/Base 内容（走 lark-doc / lark-sheets / lark-base）。"
+version: 1.0.0
+description: "飞书知识库：管理知识空间、空间成员和文档节点。创建和查询知识空间、查看和管理空间成员、管理节点层级结构、在知识库中组织文档和快捷方式。当用户需要在知识库中查找或创建文档、浏览知识空间结构、查看或管理空间成员、移动或复制节点时使用。当用户给出 doubao.com 的 /wiki/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -32,7 +32,6 @@ metadata:
   - **关键安全约束**：无论精确还是模糊，**无论命中 1 条还是多条，发起删除前都必须把候选（`name` + `space_id` + `description` + `space_type`）列给用户，由用户明确选定一个 `space_id` 再执行**。不要因为"只命中一条"就自动执行删除。
   - 命中 0 条：停下来问用户是名称拼错了还是调用方无权限；**不要**自行改名字重试。
   - 用户明确选定后再执行 `lark-cli wiki +delete-space --space-id <ID> --yes`（高风险写操作，必须显式 `--yes`）。
-  - 反例：不要把 wiki URL / 名称直接当 `--space-id`（如 `--space-id "https://.../wiki/<wiki_token>"`）；务必先用 `wiki spaces get_node` 解析出 `data.node.space_id` 再传。
 - 用户要在知识库中创建新节点，优先使用 `lark-cli wiki +node-create`。
 - 用户说“给知识库添加成员/管理员”：先把目标解析成“用户 / 群 / 部门 / 应用”四类之一，再决定 `--member-type`，不要先调 `wiki +member-add` 再根据报错反推类型。
 - 用户说“部门 + bot”：这是已知不支持路径。不要继续尝试 `wiki +member-add --as bot`；直接提示必须改成 `--as user`，或明确告知当前要求无法完成。
@@ -40,6 +39,23 @@ metadata:
 - 用户说“查看 / 列出空间成员”：用 `wiki +member-list`；该 shortcut 默认只取一页，多成员场景显式加 `--page-all`。
 - 用户说“移除 / 删除空间成员”：用 `wiki +member-remove`，必须传齐原始授予时的 `--member-type` 和 `--member-role`（不知道就先 `wiki +member-list` 查一下）。
 
+## 成员添加流程
+
+- 调用 `lark-cli wiki +member-add` 前，先把自然语言里的“人 / 群 / 部门 / 应用”解析成正确的 `--member-id`，不要猜格式。
+- 用户场景默认优先 `--member-type=openid`：用 `lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --format json` 获取 `open_id`。
+- 群组场景使用 `--member-type=openchat`：用 `lark-cli im +chat-search --query "<群名关键词>" --format json` 获取 `chat_id`。
+- 应用场景使用 `--member-type=appid`：`--member-id` 传应用 ID，格式通常为 `cli_xxx`。
+- `userid` / `unionid` 只在下游明确要求时才使用；先拿到 `open_id`，再调用 `lark-cli api GET /open-apis/contact/v3/users/<open_id> --params '{"user_id_type":"open_id"}' --format json` 读取 `user_id` / `union_id`。
+- 部门场景使用 `--member-type=opendepartmentid`：当前 CLI 没有 shortcut，需调用 `lark-cli api POST /open-apis/contact/v3/departments/search --as user --params '{"department_id_type":"open_department_id"}' --data '{"query":"<部门名>"}'` 获取 `open_department_id`。
+- 只有在目标类型和身份都已确认可行后，才调用 `lark-cli wiki +member-add`。对于部门场景，这意味着必须是 `--as user`。
+
+## 目标语义约束
+
+- `我的文档库` / `My Document Library` / `我的知识库` / `个人知识库` / `my_library` 都应视为 **Wiki personal library**，不是 Drive 根目录
+- 处理这类目标时，先解析 `my_library` 对应的真实 `space_id`，再执行 `wiki +move`、`wiki +node-create` 或其他 Wiki 写操作
+- 不要因为缺少显式 `space_id` 就退化成 `drive +move`
+- 如果用户明确说的是 Drive 文件夹、云空间（云盘/云存储）根目录、`我的空间`，才进入 Drive 域处理
+
 ## Shortcuts（推荐优先使用）
 
 Shortcut 是对常用操作的高级封装（`lark-cli wiki +<verb> [flags]`）。有 Shortcut 的操作优先使用。
@@ -59,30 +75,15 @@ Shortcut 是对常用操作的高级封装（`lark-cli wiki +<verb> [flags]`）
 | [`+member-remove`](references/lark-wiki-member-remove.md) | Remove a member from a wiki space |
 | [`+member-list`](references/lark-wiki-member-list.md) | List members of a wiki space (supports pagination) |
 
-## 成员添加流程
-
-- 调用 `lark-cli wiki +member-add` 前，先把自然语言里的“人 / 群 / 部门 / 应用”解析成正确的 `--member-id`，不要猜格式。
-- 用户场景默认优先 `--member-type=openid`：用 `lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --format json` 获取 `open_id`。
-- 群组场景使用 `--member-type=openchat`：用 `lark-cli im +chat-search --query "<群名关键词>" --format json` 获取 `chat_id`。
-- 应用场景使用 `--member-type=appid`：`--member-id` 传应用 ID，格式通常为 `cli_xxx`。
-- `userid` / `unionid` 只在下游明确要求时才使用；先拿到 `open_id`，再调用 `lark-cli api GET /open-apis/contact/v3/users/<open_id> --params '{"user_id_type":"open_id"}' --format json` 读取 `user_id` / `union_id`。
-- 部门场景使用 `--member-type=opendepartmentid`：当前 CLI 没有 shortcut，需调用 `lark-cli api POST /open-apis/contact/v3/departments/search --as user --params '{"department_id_type":"open_department_id"}' --data '{"query":"<部门名>"}'` 获取 `open_department_id`。
-- 只有在目标类型和身份都已确认可行后，才调用 `lark-cli wiki +member-add`。对于部门场景，这意味着必须是 `--as user`。
-
-## 目标语义约束
-
-- `我的文档库` / `My Document Library` / `我的知识库` / `个人知识库` / `my_library` 都应视为 **Wiki personal library**，不是 Drive 根目录
-- 处理这类目标时，先解析 `my_library` 对应的真实 `space_id`，再执行 `wiki +move`、`wiki +node-create` 或其他 Wiki 写操作
-- 不要因为缺少显式 `space_id` 就退化成 `drive +move`
-- 如果用户明确说的是 Drive 文件夹、云空间（云盘/云存储）根目录、`我的空间`，才进入 Drive 域处理
-
 ## API Resources
 
 ```bash
-lark-cli schema wiki.<resource>.<method>   # 调用原生 API 前必须先查看 --data / --params 参数结构，不要猜测字段格式
-lark-cli wiki <resource> <method> [flags]  # 调用 API
+lark-cli schema wiki.<resource>.<method>   # 调用 API 前必须先查看参数结构
+lark-cli wiki <resource> <method> [flags] # 调用 API
 ```
 
+> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+
 ### spaces
 
 - `create` — 创建知识空间
@@ -102,9 +103,18 @@ lark-cli wiki <resource> <method> [flags]  # 调用 API
 - `create` — 创建知识空间节点
 - `list` — 获取知识空间子节点列表
 
-## 不在本 skill 范围
+## 权限表
 
-- 上传 / 下载文件到知识库节点下 → [`lark-drive`](../lark-drive/SKILL.md)（`drive +upload --wiki-token`）
-- 编辑文档正文内容 → [`lark-doc`](../lark-doc/SKILL.md)
-- 表格 / 多维表格数据操作 → [`lark-sheets`](../lark-sheets/SKILL.md) / [`lark-base`](../lark-base/SKILL.md)
-- 按名称搜索文档 / Wiki / 表格文件、评论与权限管理 → [`lark-drive`](../lark-drive/SKILL.md)
+| 方法 | 所需 scope |
+|------|-----------|
+| `spaces.create` | `wiki:space:write_only` |
+| `spaces.get` | `wiki:space:read` |
+| `spaces.get_node` | `wiki:node:read` |
+| `spaces.list` | `wiki:space:retrieve` |
+| `members.create` | `wiki:member:create` |
+| `members.delete` | `wiki:member:update` |
+| `members.list` | `wiki:member:retrieve` |
+| `nodes.copy` | `wiki:node:copy` |
+| `nodes.move` | `wiki:node:move` |
+| `nodes.create` | `wiki:node:create` |
+| `nodes.list` | `wiki:node:retrieve` |

skills_embed.go

@@ -1,35 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package main
-
-import (
-	"embed"
-	"fmt"
-	"io/fs"
-	"os"
-
-	"github.com/larksuite/cli/cmd"
-)
-
-// skillsEmbedFS embeds each skill's agent-readable content (SKILL.md +
-// references/, plus lark-whiteboard's routes/ and scenes/) so the CLI serves
-// content matching the binary version; machine-resource dirs (assets/, scripts/)
-// are excluded, saving ~3.3 MB. It's a whitelist — a new subdirectory type is
-// silently omitted until added here.
-//
-//go:embed skills/*/SKILL.md skills/*/references skills/*/routes skills/*/scenes
-var skillsEmbedFS embed.FS
-
-// init wires the embedded tree in as the default skill content. It compiles into
-// `go build .` but not the single-file preview build (`go build ./main.go`), so
-// main.go stays self-contained and that build still compiles (shipping no
-// embedded skills). Assembly failure warns on stderr rather than panicking.
-func init() {
-	sub, err := fs.Sub(skillsEmbedFS, "skills")
-	if err != nil {
-		fmt.Fprintln(os.Stderr, "warning: skills embed assembly failed, skills commands disabled:", err)
-		return
-	}
-	cmd.SetEmbeddedSkillContent(sub)
-}

tests/cli_e2e/docs/coverage.md

@@ -9,7 +9,6 @@
 - TestDocs_CreateAndFetchWorkflow: proves `docs +create` and `docs +fetch`; key `t.Run(...)` proof points are `create as bot` and `fetch as bot`.
 - TestDocs_CreateAndFetchWorkflowAsUser: proves the same shortcut pair with UAT injection via `create as user` and `fetch as user`; creates its own Drive folder fixture first, then reads back the created doc by token.
 - TestDocs_UpdateWorkflow: proves `docs +update` via `update-title-and-content as bot`, then re-fetches the same doc in `verify as bot` to assert persisted title/content changes.
-- TestDocs_DryRunDefaultsToV2OpenAPI: proves `docs +create`, `docs +fetch`, and `docs +update` dry-run all emit `/open-apis/docs_ai/v1/...` requests without MCP or `--api-version` guidance.
 - Setup note: docs workflows create a Drive folder through `drive files create_folder` in `helpers_test.go`; that helper is external to the docs domain and is not counted here.
 - Blocked area: media and search shortcuts still need deterministic fixtures and local file orchestration.
 
@@ -17,11 +16,11 @@
 
 | Status | Cmd | Type | Testcase | Key parameter shapes | Notes / uncovered reason |
 | --- | --- | --- | --- | --- | --- |
-| ✓ | docs +create | shortcut | docs/helpers_test.go::createDocWithRetry; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/create as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/create | `--parent-token`; `--doc-format markdown`; `--content` | helper asserts returned doc id from `data.document.document_id` |
-| ✓ | docs +fetch | shortcut | docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflow/fetch as bot; docs_update_test.go::TestDocs_UpdateWorkflow/verify as bot; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/fetch as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/fetch | `--doc <docToken>`; `--doc-format markdown` | |
+| ✓ | docs +create | shortcut | docs/helpers_test.go::createDocWithRetry; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/create as user | `--folder-token`; `--title`; `--markdown` | helper asserts returned doc id |
+| ✓ | docs +fetch | shortcut | docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflow/fetch as bot; docs_update_test.go::TestDocs_UpdateWorkflow/verify as bot; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/fetch as user | `--doc <docToken>` | |
 | ✕ | docs +media-download | shortcut |  | none | no media fixture workflow yet |
 | ✕ | docs +media-insert | shortcut |  | none | requires deterministic upload fixture and rollback assertions |
 | ✕ | docs +media-preview | shortcut |  | none | requires deterministic media fixture |
 | ✕ | docs +search | shortcut |  | none | search results are ambient and not yet stabilized for E2E |
-| ✓ | docs +update | shortcut | docs_update_test.go::TestDocs_UpdateWorkflow/update-title-and-content as bot; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/update | `--doc`; `--command overwrite`; `--doc-format markdown`; `--content` | |
+| ✓ | docs +update | shortcut | docs_update_test.go::TestDocs_UpdateWorkflow/update-title-and-content as bot | `--doc`; `--mode overwrite`; `--markdown`; `--new-title` | |
 | ✕ | docs +whiteboard-update | shortcut |  | none | requires whiteboard fixture and DSL-specific assertions |

tests/cli_e2e/docs/docs_create_fetch_test.go

@@ -41,15 +41,12 @@ func TestDocs_CreateAndFetchWorkflowAsBot(t *testing.T) {
 			Args: []string{
 				"docs", "+fetch",
 				"--doc", docToken,
-				"--doc-format", "markdown",
 			},
 		})
 		require.NoError(t, err)
 		result.AssertExitCode(t, 0)
 		result.AssertStdoutStatus(t, true)
-		content := gjson.Get(result.Stdout, "data.document.content").String()
-		assert.Contains(t, content, docTitle)
-		assert.Contains(t, content, "This document was created by lark-cli e2e test.")
+		assert.Equal(t, docTitle, gjson.Get(result.Stdout, "data.title").String())
 	})
 }
 
@@ -76,14 +73,12 @@ func TestDocs_CreateAndFetchWorkflowAsUser(t *testing.T) {
 		require.NotEmpty(t, docToken, "document token should be created before fetch")
 
 		result, err := clie2e.RunCmd(ctx, clie2e.Request{
-			Args:      []string{"docs", "+fetch", "--doc", docToken, "--doc-format", "markdown"},
+			Args:      []string{"docs", "+fetch", "--doc", docToken},
 			DefaultAs: defaultAs,
 		})
 		require.NoError(t, err)
 		result.AssertExitCode(t, 0)
 		result.AssertStdoutStatus(t, true)
-		content := gjson.Get(result.Stdout, "data.document.content").String()
-		assert.Contains(t, content, docTitle)
-		assert.Contains(t, content, "Created with user access token.")
+		assert.Equal(t, docTitle, gjson.Get(result.Stdout, "data.title").String())
 	})
 }

tests/cli_e2e/docs/docs_update_dryrun_test.go

@@ -13,7 +13,20 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
+// TestDocs_UpdateDryRunSuppressesSemanticWarnings asserts the contract that
+// docsUpdateWarnings is NOT invoked on the --dry-run path. The unit tests in
+// shortcuts/doc/docs_update_check_test.go prove the helper emits warnings for
+// replace_range + blank-line and for combined-emphasis markers; this E2E
+// locks in that they never reach the user during dry-run planning, so a
+// future refactor that moves warning emission into a shared code path can't
+// silently regress.
+//
+// Input is intentionally crafted to trigger BOTH warnings the helper emits:
+//   - mode=replace_range + markdown containing "\n\n" (blank-line warning)
+//   - markdown containing `***combined***` (combined bold+italic warning)
+//
+// Neither string may appear in dry-run output.
+func TestDocs_UpdateDryRunSuppressesSemanticWarnings(t *testing.T) {
 	// Fake creds are enough — dry-run short-circuits before any real API call.
 	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
 	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
@@ -22,76 +35,36 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	t.Cleanup(cancel)
 
-	tests := []struct {
-		name    string
-		args    []string
-		wantURL string
-	}{
-		{
-			name: "create",
-			args: []string{
-				"docs", "+create",
-				"--content", "<title>Dry Run</title><p>hello</p>",
-				"--dry-run",
-			},
-			wantURL: "/open-apis/docs_ai/v1/documents",
-		},
-		{
-			name: "create api-version v1 compatibility",
-			args: []string{
-				"docs", "+create",
-				"--api-version", "v1",
-				"--content", "<title>Dry Run</title><p>hello</p>",
-				"--dry-run",
-			},
-			wantURL: "/open-apis/docs_ai/v1/documents",
-		},
-		{
-			name: "fetch",
-			args: []string{
-				"docs", "+fetch",
-				"--doc", "doxcnDryRunE2E",
-				"--dry-run",
-			},
-			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E/fetch",
-		},
-		{
-			name: "update",
-			args: []string{
-				"docs", "+update",
-				"--doc", "doxcnDryRunE2E",
-				"--command", "append",
-				"--content", "<p>hello</p>",
-				"--dry-run",
-			},
-			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E",
-		},
-	}
+	// "***combined***" is a triple-asterisk combined-emphasis shape; "\n\n"
+	// is a paragraph break. Both would normally produce warnings when
+	// Execute runs under --mode=replace_range; both must be absent here.
+	markdown := "***combined***\n\nsecond paragraph"
 
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result, err := clie2e.RunCmd(ctx, clie2e.Request{
-				Args:      tt.args,
-				DefaultAs: "bot",
-			})
-			require.NoError(t, err)
-			result.AssertExitCode(t, 0)
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"docs", "+update",
+			"--doc", "doxcnDryRunE2E",
+			"--mode", "replace_range",
+			"--selection-with-ellipsis", "placeholder",
+			"--markdown", markdown,
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
 
-			combined := result.Stdout + "\n" + result.Stderr
-			for _, want := range []string{
-				tt.wantURL,
-				"docs_ai/v1",
-			} {
-				if !strings.Contains(combined, want) {
-					t.Fatalf("dry-run output missing %q\nstdout:\n%s\nstderr:\n%s", want, result.Stdout, result.Stderr)
-				}
-			}
-			if strings.Contains(combined, "/mcp") || strings.Contains(combined, "MCP tool") {
-				t.Fatalf("dry-run output should not use MCP\nstdout:\n%s\nstderr:\n%s", result.Stdout, result.Stderr)
-			}
-			if strings.Contains(combined, "--api-version") {
-				t.Fatalf("dry-run output should not ask for --api-version\nstdout:\n%s\nstderr:\n%s", result.Stdout, result.Stderr)
-			}
-		})
+	// Neither warning prefix ("warning:") nor either specific warning body
+	// may appear in dry-run output (stdout OR stderr).
+	combined := result.Stdout + "\n" + result.Stderr
+	for _, needle := range []string{
+		"warning:",
+		"does not split a block into multiple paragraphs",
+		"combined bold+italic markers",
+	} {
+		if strings.Contains(combined, needle) {
+			t.Errorf("dry-run output must not surface pre-write warning %q\nstdout:\n%s\nstderr:\n%s",
+				needle, result.Stdout, result.Stderr)
+		}
 	}
 }

tests/cli_e2e/docs/docs_update_test.go

@@ -43,9 +43,9 @@ func TestDocs_UpdateWorkflow(t *testing.T) {
 			Args: []string{
 				"docs", "+update",
 				"--doc", docToken,
-				"--command", "overwrite",
-				"--doc-format", "markdown",
-				"--content", "# " + updatedTitle + "\n\n" + updatedContent,
+				"--mode", "overwrite",
+				"--markdown", updatedContent,
+				"--new-title", updatedTitle,
 			},
 			DefaultAs: defaultAs,
 		})
@@ -61,15 +61,12 @@ func TestDocs_UpdateWorkflow(t *testing.T) {
 			Args: []string{
 				"docs", "+fetch",
 				"--doc", docToken,
-				"--doc-format", "markdown",
 			},
 			DefaultAs: defaultAs,
 		})
 		require.NoError(t, err)
 		result.AssertExitCode(t, 0)
 		result.AssertStdoutStatus(t, true)
-		content := gjson.Get(result.Stdout, "data.document.content").String()
-		assert.Contains(t, content, updatedTitle)
-		assert.Contains(t, content, "This is the updated content.")
+		assert.Equal(t, updatedTitle, gjson.Get(result.Stdout, "data.title").String())
 	})
 }