docs(sheets): clarify chart labels field is presence-toggle, not value-toggle

Synced from sheet-skill-spec. Chart labels (plotArea.plot.labels and per-series
labels) are toggled by object existence — passing labels at all turns data
labels on, even when value/category/series/percentage are all false (server
falls back to showing value). Models repeatedly try `{ value: false, category:
false, series: false }` to disable, which silently shows the value fallback.
The reference doc now spells out both directions: pass labels to show, omit
the whole labels field to hide.

Also picks up earlier spec-side drift not yet propagated:
- pivot-table reference: +pivot-list info return + overlap validation
- flag-defs: cell-matrix fan-out cap default 200000 -> 50000 (#1578)

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.59] - 2026-06-26
+
+### Features
+
+- **slides**: Add `+replace-pages` and `xml get` shortcuts, and expose the presentation URL (#1585)
+- **minutes**: Support speaker list and no-Lark speaker replace (#1594)
+- **calendar/vc/minutes**: Optimize and extend calendar, vc, minutes, and note shortcuts and skills (#1571)
+
+### Bug Fixes
+
+- **docs**: Hide docs `api-version` compat flag (#1580)
+
 ## [v1.0.58] - 2026-06-25
 
 ### Features
@@ -1265,6 +1277,7 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.59]: https://github.com/larksuite/cli/releases/tag/v1.0.59
 [v1.0.58]: https://github.com/larksuite/cli/releases/tag/v1.0.58
 [v1.0.57]: https://github.com/larksuite/cli/releases/tag/v1.0.57
 [v1.0.56]: https://github.com/larksuite/cli/releases/tag/v1.0.56

README.md

@@ -198,7 +198,7 @@ Prefixed with `+`, designed to be friendly for both humans and AI, with smart de
 ```bash
 lark-cli calendar +agenda
 lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
-lark-cli docs +create --api-version v2 --doc-format markdown --content $'<title>Weekly Report</title>\n# Progress\n- Completed feature X'
+lark-cli docs +create --doc-format markdown --content $'<title>Weekly Report</title>\n# Progress\n- Completed feature X'
 ```
 
 Run `lark-cli <service> --help` to see all shortcut commands.

README.zh.md

@@ -199,7 +199,7 @@ CLI 提供三种粒度的调用方式，覆盖从快速操作到完全自定义
 ```bash
 lark-cli calendar +agenda
 lark-cli im +messages-send --chat-id "oc_xxx" --text "Hello"
-lark-cli docs +create --api-version v2 --doc-format markdown --content $'<title>周报</title>\n# 本周进展\n- 完成了 X 功能'
+lark-cli docs +create --doc-format markdown --content $'<title>周报</title>\n# 本周进展\n- 完成了 X 功能'
 ```
 
 运行 `lark-cli <service> --help` 查看所有快捷命令。

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.58",
+  "version": "1.0.59",
   "description": "The official CLI for Lark/Feishu open platform",
   "bin": {
     "lark-cli": "scripts/run.js"

shortcuts/calendar/calendar_meeting.go

@@ -0,0 +1,215 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// calendar +meeting — get meeting info for calendar events via mget_instance_relation_info
+
+package calendar
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const meetingLogPrefix = "[calendar +meeting]"
+
+// mgetInstanceRelationRequestBody is the request body for mget_instance_relation_info API.
+type mgetInstanceRelationRequestBody struct {
+	InstanceIDs            []string `json:"instance_ids"`
+	NeedMeetingInstanceIDs bool     `json:"need_meeting_instance_ids"`
+	NeedMeetingNotes       bool     `json:"need_meeting_notes"`
+	NeedAIMeetingNotes     bool     `json:"need_ai_meeting_notes"`
+}
+
+// meetingInfoItem represents a single event's meeting info in the output.
+type meetingInfoItem struct {
+	EventID     string `json:"event_id"`
+	MeetingID   string `json:"meeting_id,omitempty"`
+	MeetingNote string `json:"meeting_note,omitempty"`
+	Error       string `json:"error,omitempty"`
+	Hint        string `json:"hint,omitempty"`
+}
+
+// translateFailMsg converts API fail_msg to a user-friendly error message.
+func translateFailMsg(failMsg string) string {
+	switch failMsg {
+	case "No Permission":
+		return "no read permission for this calendar event (not a participant of the event)"
+	case "Not Found":
+		return "event not found on the specified calendar (event ID may be incorrect or does not belong to this calendar)"
+	default:
+		return failMsg
+	}
+}
+
+// fetchEventMeetingInfo queries mget_instance_relation_info for a single event instance.
+func fetchEventMeetingInfo(ctx context.Context, runtime *common.RuntimeContext, instanceID, calendarID string) *meetingInfoItem {
+	body := &mgetInstanceRelationRequestBody{
+		InstanceIDs:            []string{instanceID},
+		NeedMeetingInstanceIDs: true,
+		NeedMeetingNotes:       true,
+		NeedAIMeetingNotes:     false,
+	}
+
+	data, err := runtime.CallAPITyped("POST",
+		fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/mget_instance_relation_info", validate.EncodePathSegment(calendarID)),
+		nil, body)
+	if err != nil {
+		msg := unwrapCalendarAPIError(err)
+		if msg == "" {
+			msg = err.Error()
+		}
+		return &meetingInfoItem{EventID: instanceID, Error: msg}
+	}
+
+	// Check for failed instance IDs first
+	if failedIDs, _ := data["failed_instance_ids"].([]any); len(failedIDs) > 0 {
+		for _, raw := range failedIDs {
+			if failInfo, ok := raw.(map[string]any); ok {
+				if failID, _ := failInfo["instance_id"].(string); failID == instanceID {
+					failMsg, _ := failInfo["fail_msg"].(string)
+					return &meetingInfoItem{EventID: instanceID, Error: translateFailMsg(failMsg)}
+				}
+			}
+		}
+	}
+
+	infos, _ := data["instance_relation_infos"].([]any)
+	if len(infos) == 0 {
+		return &meetingInfoItem{EventID: instanceID, Error: "no event relation info found"}
+	}
+
+	info, _ := infos[0].(map[string]any)
+	result := &meetingInfoItem{EventID: instanceID}
+
+	// Extract meeting_id (return first if multiple) — API returns string
+	if rawIDs, _ := info["meeting_instance_ids"].([]any); len(rawIDs) > 0 {
+		if id, ok := rawIDs[0].(string); ok && id != "" {
+			result.MeetingID = id
+		}
+	}
+
+	// Extract meeting_note (return first if multiple)
+	if notes, _ := info["meeting_notes"].([]any); len(notes) > 0 {
+		if note, ok := notes[0].(string); ok && note != "" {
+			result.MeetingNote = note
+		}
+	}
+
+	// Add hints for empty resources (independent checks)
+	var emptyFields []string
+	if result.MeetingID == "" {
+		emptyFields = append(emptyFields, "meeting_id")
+	}
+	if result.MeetingNote == "" {
+		emptyFields = append(emptyFields, "meeting_note")
+	}
+	if len(emptyFields) > 0 {
+		result.Hint = fmt.Sprintf("%s not found for this event", strings.Join(emptyFields, ", "))
+	}
+
+	return result
+}
+
+// CalendarMeeting gets meeting info for calendar events.
+var CalendarMeeting = common.Shortcut{
+	Service:     "calendar",
+	Command:     "+meeting",
+	Description: "Get meeting info for calendar events (meeting_id, meeting_note)",
+	Risk:        "read",
+	Scopes:      []string{"calendar:calendar.event:read"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "event-ids", Desc: "calendar event instance IDs, comma-separated for batch", Required: true},
+		{Name: "calendar-id", Desc: "calendar ID (default: primary)"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := rejectCalendarAutoBotFallback(runtime); err != nil {
+			return err
+		}
+		ids := common.SplitCSV(runtime.Str("event-ids"))
+		const maxBatchSize = 50
+		if len(ids) > maxBatchSize {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--event-ids: too many IDs (%d), maximum is %d", len(ids), maxBatchSize).WithParam("--event-ids")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		calendarID := runtime.Str("calendar-id")
+		if calendarID == "" {
+			calendarID = "<primary>"
+		}
+		return common.NewDryRunAPI().
+			POST(fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/mget_instance_relation_info", calendarID)).
+			Set("event_ids", common.SplitCSV(runtime.Str("event-ids"))).
+			Set("calendar_id", calendarID)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		errOut := runtime.IO().ErrOut
+		instanceIDs := common.SplitCSV(runtime.Str("event-ids"))
+		calendarID := strings.TrimSpace(runtime.Str("calendar-id"))
+		if calendarID == "" {
+			calendarID = PrimaryCalendarIDStr
+		}
+
+		results := make([]*meetingInfoItem, 0, len(instanceIDs))
+		fmt.Fprintf(errOut, "%s querying %d event_id(s)\n", meetingLogPrefix, len(instanceIDs))
+		for _, id := range instanceIDs {
+			if err := ctx.Err(); err != nil {
+				return err
+			}
+			fmt.Fprintf(errOut, "%s querying event_id=%s ...\n", meetingLogPrefix, id)
+			results = append(results, fetchEventMeetingInfo(ctx, runtime, id, calendarID))
+		}
+
+		successCount := 0
+		for _, r := range results {
+			if r.Error == "" {
+				successCount++
+			}
+		}
+		fmt.Fprintf(errOut, "%s done: %d total, %d succeeded, %d failed\n", meetingLogPrefix, len(results), successCount, len(results)-successCount)
+
+		if successCount == 0 && len(results) > 0 {
+			return runtime.OutPartialFailure(map[string]any{"meetings": results}, &output.Meta{Count: len(results)})
+		}
+
+		outData := map[string]any{"meetings": results}
+		runtime.OutFormat(outData, &output.Meta{Count: len(results)}, func(w io.Writer) {
+			if len(results) == 0 {
+				fmt.Fprintln(w, "No events.")
+				return
+			}
+			var rows []map[string]interface{}
+			for _, r := range results {
+				row := map[string]interface{}{"event_id": r.EventID}
+				if r.Error != "" {
+					row["status"] = "FAIL"
+					row["error"] = r.Error
+				} else {
+					row["status"] = "OK"
+					if r.MeetingID != "" {
+						row["meeting_id"] = r.MeetingID
+					}
+					if r.MeetingNote != "" {
+						row["meeting_note"] = r.MeetingNote
+					}
+					if r.Hint != "" {
+						row["hint"] = r.Hint
+					}
+				}
+				rows = append(rows, row)
+			}
+			output.PrintTable(w, rows)
+			fmt.Fprintf(w, "\n%d event(s), %d succeeded, %d failed\n", len(results), successCount, len(results)-successCount)
+		})
+		return nil
+	},
+}

shortcuts/calendar/calendar_meeting_test.go

@@ -0,0 +1,484 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package calendar
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"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"
+)
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+var calWarmOnce sync.Once
+
+func calWarmTokenCache(t *testing.T) {
+	t.Helper()
+	calWarmOnce.Do(func() {
+		f, _, _, reg := cmdutil.TestFactory(t, calDefaultConfig())
+		reg.Register(&httpmock.Stub{
+			URL:  "/open-apis/test/v1/warm",
+			Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{}},
+		})
+		s := common.Shortcut{
+			Service:   "test",
+			Command:   "+warm",
+			AuthTypes: []string{"bot"},
+			Execute: func(_ context.Context, rctx *common.RuntimeContext) error {
+				_, err := rctx.CallAPITyped("GET", "/open-apis/test/v1/warm", nil, nil)
+				return err
+			},
+		}
+		parent := &cobra.Command{Use: "test"}
+		s.Mount(parent, f)
+		parent.SetArgs([]string{"+warm"})
+		parent.SilenceErrors = true
+		parent.SilenceUsage = true
+		parent.Execute()
+	})
+}
+
+func calDefaultConfig() *core.CliConfig {
+	return &core.CliConfig{
+		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+		UserOpenId: "ou_testuser",
+	}
+}
+
+func calMountAndRun(t *testing.T, s common.Shortcut, args []string, f *cmdutil.Factory, stdout *bytes.Buffer) error {
+	t.Helper()
+	calWarmTokenCache(t)
+	parent := &cobra.Command{Use: "calendar"}
+	s.Mount(parent, f)
+	parent.SetArgs(args)
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	if stdout != nil {
+		stdout.Reset()
+	}
+	return parent.Execute()
+}
+
+// ---------------------------------------------------------------------------
+// calendar +meeting tests
+// ---------------------------------------------------------------------------
+
+func mgetInstanceRelationStub(calendarID, instanceID string, meetingIDs []string, meetingNotes []string, aiMeetingNotes []string) *httpmock.Stub {
+	infos := map[string]interface{}{
+		"instance_id": instanceID,
+	}
+	mIDs := make([]interface{}, len(meetingIDs))
+	for i, id := range meetingIDs {
+		mIDs[i] = id
+	}
+	infos["meeting_instance_ids"] = mIDs
+	if len(meetingNotes) > 0 {
+		notes := make([]interface{}, len(meetingNotes))
+		for i, n := range meetingNotes {
+			notes[i] = n
+		}
+		infos["meeting_notes"] = notes
+	}
+	if len(aiMeetingNotes) > 0 {
+		notes := make([]interface{}, len(aiMeetingNotes))
+		for i, n := range aiMeetingNotes {
+			notes[i] = n
+		}
+		infos["ai_meeting_notes"] = notes
+	}
+	return &httpmock.Stub{
+		Method: "POST",
+		URL:    fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/mget_instance_relation_info", calendarID),
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"instance_relation_infos": []interface{}{infos},
+			},
+		},
+	}
+}
+
+func mgetInstanceRelationFailedStub(calendarID, instanceID, failMsg string) *httpmock.Stub {
+	return &httpmock.Stub{
+		Method: "POST",
+		URL:    fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/mget_instance_relation_info", calendarID),
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"instance_relation_infos": []interface{}{},
+				"failed_instance_ids": []interface{}{
+					map[string]interface{}{
+						"instance_id": instanceID,
+						"fail_msg":    failMsg,
+					},
+				},
+			},
+		},
+	}
+}
+
+func TestMeeting_Validation_MissingEventIDs(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, calDefaultConfig())
+	err := calMountAndRun(t, CalendarMeeting, []string{"+meeting", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for missing --event-ids")
+	}
+}
+
+func TestMeeting_Validation_BatchLimit(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, calDefaultConfig())
+	ids := make([]string, 51)
+	for i := range ids {
+		ids[i] = fmt.Sprintf("evt%d", i)
+	}
+	err := calMountAndRun(t, CalendarMeeting, []string{"+meeting", "--event-ids", strings.Join(ids, ","), "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected batch limit error")
+	}
+	if !strings.Contains(err.Error(), "too many IDs") {
+		t.Errorf("expected 'too many IDs' error, got: %v", err)
+	}
+}
+
+func TestMeeting_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, calDefaultConfig())
+	err := calMountAndRun(t, CalendarMeeting, []string{"+meeting", "--event-ids", "evt001", "--dry-run", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "mget_instance_relation_info") {
+		t.Errorf("dry-run should show mget API path, got: %s", stdout.String())
+	}
+}
+
+func TestMeeting_Execute_Success(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, calDefaultConfig())
+	reg.Register(mgetInstanceRelationStub("primary", "evt_m1", []string{"123456"}, []string{"doc_note1"}, []string{"doc_ai1"}))
+
+	err := calMountAndRun(t, CalendarMeeting, []string{"+meeting", "--event-ids", "evt_m1", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meetings, _ := data["meetings"].([]any)
+	if len(meetings) != 1 {
+		t.Fatalf("expected 1 meeting, got %d", len(meetings))
+	}
+	m, _ := meetings[0].(map[string]any)
+	if m["meeting_id"] != "123456" {
+		t.Errorf("meeting_id = %v, want 123456", m["meeting_id"])
+	}
+	if m["meeting_note"] != "doc_note1" {
+		t.Errorf("meeting_note = %v, want doc_note1", m["meeting_note"])
+	}
+	if _, hasAI := m["ai_meeting_note"]; hasAI {
+		t.Error("ai_meeting_note should not be present in output")
+	}
+}
+
+func TestMeeting_Execute_FailedInstance(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, calDefaultConfig())
+	reg.Register(mgetInstanceRelationFailedStub("primary", "evt_fail", "No Permission"))
+
+	err := calMountAndRun(t, CalendarMeeting, []string{"+meeting", "--event-ids", "evt_fail", "--as", "user"}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+	// Verify translated fail_msg appears in output
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err == nil {
+		data, _ := resp["data"].(map[string]any)
+		meetings, _ := data["meetings"].([]any)
+		if len(meetings) > 0 {
+			m, _ := meetings[0].(map[string]any)
+			if errMsg, _ := m["error"].(string); !strings.Contains(errMsg, "no read permission") {
+				t.Errorf("expected translated fail_msg, got: %v", errMsg)
+			}
+		}
+	}
+}
+
+func TestMeeting_Execute_NoMeeting(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, calDefaultConfig())
+	reg.Register(mgetInstanceRelationStub("primary", "evt_nomeet", []string{}, nil, nil))
+
+	err := calMountAndRun(t, CalendarMeeting, []string{"+meeting", "--event-ids", "evt_nomeet", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meetings, _ := data["meetings"].([]any)
+	if len(meetings) != 1 {
+		t.Fatalf("expected 1 meeting, got %d", len(meetings))
+	}
+	m, _ := meetings[0].(map[string]any)
+	if hint, _ := m["hint"].(string); !strings.Contains(hint, "meeting_id") {
+		t.Errorf("expected hint about meeting_id, got: %v", hint)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// calendar +search-event tests
+// ---------------------------------------------------------------------------
+
+func TestSearchEvent_Validation_InvalidTimeRange(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, calDefaultConfig())
+	err := calMountAndRun(t, CalendarSearchEvent, []string{"+search-event", "--start", "bad-format", "--end", "2026-04-27", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for invalid --start")
+	}
+	if !strings.Contains(err.Error(), "--start") {
+		t.Errorf("unexpected error: %v", err)
+	}
+}
+
+func TestSearchEvent_Validation_TimeRangeStartAfterEnd(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, calDefaultConfig())
+	err := calMountAndRun(t, CalendarSearchEvent, []string{"+search-event", "--start", "2026-04-27", "--end", "2026-04-20", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for start after end")
+	}
+}
+
+func TestSearchEvent_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, calDefaultConfig())
+	err := calMountAndRun(t, CalendarSearchEvent, []string{"+search-event", "--query", "周会", "--dry-run", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "search_event") {
+		t.Errorf("dry-run should show search_event API path, got: %s", stdout.String())
+	}
+}
+
+func TestSearchEvent_Execute_Success(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, calDefaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/primary/events/search_event",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"items": []interface{}{
+					map[string]interface{}{
+						"display_info": "Q2 周会\n2026-04-23 15:00-16:00",
+						"meta_data": map[string]interface{}{
+							"event_id": "evt_search1",
+							"summary":  "Q2 周会",
+							"start": map[string]interface{}{
+								"date_time": "2026-04-23T15:00:00+08:00",
+								"timezone":  "Asia/Shanghai",
+							},
+							"end": map[string]interface{}{
+								"date_time": "2026-04-23T16:00:00+08:00",
+								"timezone":  "Asia/Shanghai",
+							},
+							"is_all_day": false,
+							"app_link":   "https://applink.feishu.cn/...",
+						},
+					},
+				},
+				"has_more":   false,
+				"page_token": "",
+			},
+		},
+	})
+
+	err := calMountAndRun(t, CalendarSearchEvent, []string{"+search-event", "--query", "周会", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	if data["calendar_id"] != "primary" {
+		t.Errorf("calendar_id = %v, want primary", data["calendar_id"])
+	}
+	items, _ := data["items"].([]any)
+	if len(items) != 1 {
+		t.Fatalf("expected 1 item, got %d", len(items))
+	}
+	item, _ := items[0].(map[string]any)
+	if item["event_id"] != "evt_search1" {
+		t.Errorf("event_id = %v, want evt_search1", item["event_id"])
+	}
+	if item["summary"] != "Q2 周会" {
+		t.Errorf("summary = %v, want 'Q2 周会'", item["summary"])
+	}
+}
+
+func TestSearchEvent_Execute_Empty(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, calDefaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/primary/events/search_event",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"items":    []interface{}{},
+				"has_more": false,
+			},
+		},
+	})
+
+	err := calMountAndRun(t, CalendarSearchEvent, []string{"+search-event", "--query", "nonexistent", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Pure function tests
+// ---------------------------------------------------------------------------
+
+func TestParseSearchEventTimeRange(t *testing.T) {
+	tests := []struct {
+		name    string
+		start   string
+		end     string
+		wantErr bool
+	}{
+		{"empty", "", "", false},
+		{"valid", "2026-04-20", "2026-04-27", false},
+		{"start only defaults end", "2026-04-20", "", false},
+		{"end only defaults start", "", "2026-04-27", false},
+		{"invalid start format", "not-a-date", "2026-04-27", true},
+		{"start after end", "2026-04-27", "2026-04-20", true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := &cobra.Command{Use: "test"}
+			cmd.Flags().String("start", "", "")
+			cmd.Flags().String("end", "", "")
+			if tt.start != "" {
+				_ = cmd.Flags().Set("start", tt.start)
+			}
+			if tt.end != "" {
+				_ = cmd.Flags().Set("end", tt.end)
+			}
+			runtime := common.TestNewRuntimeContext(cmd, calDefaultConfig())
+			_, _, err := parseSearchEventTimeRange(runtime)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("parseSearchEventTimeRange() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+
+	t.Run("start only fills end with end-of-day", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "test"}
+		cmd.Flags().String("start", "", "")
+		cmd.Flags().String("end", "", "")
+		_ = cmd.Flags().Set("start", "2026-04-20")
+		runtime := common.TestNewRuntimeContext(cmd, calDefaultConfig())
+		startRFC, endRFC, err := parseSearchEventTimeRange(runtime)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if !strings.HasPrefix(startRFC, "2026-04-20T00:00:00") {
+			t.Errorf("start = %s, want 2026-04-20T00:00:00...", startRFC)
+		}
+		if !strings.HasPrefix(endRFC, "2026-04-20T23:59:59") {
+			t.Errorf("end = %s, want 2026-04-20T23:59:59...", endRFC)
+		}
+	})
+
+	t.Run("end only fills start with start-of-day", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "test"}
+		cmd.Flags().String("start", "", "")
+		cmd.Flags().String("end", "", "")
+		_ = cmd.Flags().Set("end", "2026-04-27")
+		runtime := common.TestNewRuntimeContext(cmd, calDefaultConfig())
+		startRFC, endRFC, err := parseSearchEventTimeRange(runtime)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if !strings.HasPrefix(startRFC, "2026-04-27T00:00:00") {
+			t.Errorf("start = %s, want 2026-04-27T00:00:00...", startRFC)
+		}
+		if !strings.HasPrefix(endRFC, "2026-04-27T23:59:59") {
+			t.Errorf("end = %s, want 2026-04-27T23:59:59...", endRFC)
+		}
+	})
+}
+
+func TestBuildSearchEventFilter(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("attendee-ids", "", "")
+	_ = cmd.Flags().Set("attendee-ids", "ou_user1,oc_chat1,omm_room1")
+	runtime := common.TestNewRuntimeContext(cmd, calDefaultConfig())
+
+	filter := buildSearchEventFilter(runtime, "", "")
+	if filter == nil {
+		t.Fatal("expected filter to be non-nil")
+	}
+	if len(filter.AttendeeUserIDs) != 1 || filter.AttendeeUserIDs[0] != "ou_user1" {
+		t.Errorf("attendee_user_ids = %v, want [ou_user1]", filter.AttendeeUserIDs)
+	}
+	if len(filter.AttendeeChatIDs) != 1 || filter.AttendeeChatIDs[0] != "oc_chat1" {
+		t.Errorf("attendee_chat_ids = %v, want [oc_chat1]", filter.AttendeeChatIDs)
+	}
+	if len(filter.MeetingRoomIDs) != 1 || filter.MeetingRoomIDs[0] != "omm_room1" {
+		t.Errorf("meeting_room_ids = %v, want [omm_room1]", filter.MeetingRoomIDs)
+	}
+}
+
+func TestBuildSearchEventFilter_Empty(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("attendee-ids", "", "")
+	runtime := common.TestNewRuntimeContext(cmd, calDefaultConfig())
+
+	filter := buildSearchEventFilter(runtime, "", "")
+	if filter != nil {
+		t.Errorf("expected nil for empty filter, got %v", filter)
+	}
+}
+
+func TestBuildSearchEventFilter_TimeRange(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("attendee-ids", "", "")
+	runtime := common.TestNewRuntimeContext(cmd, calDefaultConfig())
+
+	filter := buildSearchEventFilter(runtime, "2026-04-20T00:00:00+08:00", "2026-04-27T23:59:59+08:00")
+	if filter == nil {
+		t.Fatal("expected filter to be non-nil")
+	}
+	if filter.TimeRange == nil {
+		t.Fatal("expected time_range in filter")
+	}
+	if filter.TimeRange.StartTime != "2026-04-20T00:00:00+08:00" {
+		t.Errorf("start_time = %v, want 2026-04-20T00:00:00+08:00", filter.TimeRange.StartTime)
+	}
+}

shortcuts/calendar/calendar_room_find.go

@@ -66,7 +66,8 @@ type roomFindSlot struct {
 type roomFindTimeSlot struct {
 	Start        string                `json:"start,omitempty"`
 	End          string                `json:"end,omitempty"`
-	MeetingRooms []*roomFindSuggestion `json:"meeting_rooms,omitempty"`
+	MeetingRooms []*roomFindSuggestion `json:"meeting_rooms"`
+	Hint         string                `json:"hint,omitempty"`
 }
 
 type roomFindOutput struct {
@@ -103,11 +104,18 @@ func collectRoomFindResults(slots []roomFindSlot, limit int, fetch func(roomFind
 				}
 				return
 			}
-			out.TimeSlots = append(out.TimeSlots, &roomFindTimeSlot{
+			if suggestions == nil {
+				suggestions = []*roomFindSuggestion{}
+			}
+			ts := &roomFindTimeSlot{
 				Start:        slot.Start,
 				End:          slot.End,
 				MeetingRooms: suggestions,
-			})
+			}
+			if len(suggestions) == 0 {
+				ts.Hint = "no meeting room matches the current filters for this slot"
+			}
+			out.TimeSlots = append(out.TimeSlots, ts)
 		}(slot)
 	}
 	wg.Wait()
@@ -374,6 +382,10 @@ var CalendarRoomFind = common.Shortcut{
 			}
 			for _, slot := range out.TimeSlots {
 				fmt.Fprintf(w, "%s - %s\n", slot.Start, slot.End)
+				if len(slot.MeetingRooms) == 0 {
+					fmt.Fprintf(w, "0 meeting room(s) found: %s\n", slot.Hint)
+					continue
+				}
 				var rows []map[string]interface{}
 				for _, room := range slot.MeetingRooms {
 					rows = append(rows, map[string]interface{}{
@@ -384,6 +396,7 @@ var CalendarRoomFind = common.Shortcut{
 					})
 				}
 				output.PrintTable(w, rows)
+				fmt.Fprintf(w, "%d meeting room(s) found\n", len(slot.MeetingRooms))
 				fmt.Fprintln(w)
 			}
 		})

shortcuts/calendar/calendar_room_find_test.go

@@ -4,6 +4,8 @@
 package calendar
 
 import (
+	"encoding/json"
+	"strings"
 	"testing"
 	"time"
 )
@@ -82,3 +84,60 @@ func TestCollectRoomFindResults_LimitsConcurrency(t *testing.T) {
 		t.Fatalf("expected %d time slots, got %d", len(slots), len(out.TimeSlots))
 	}
 }
+
+func TestCollectRoomFindResults_EmptySlotEmitsHintAndArray(t *testing.T) {
+	slots := []roomFindSlot{
+		{Start: "2026-03-27T14:00:00+08:00", End: "2026-03-27T15:00:00+08:00"},
+		{Start: "2026-03-27T15:00:00+08:00", End: "2026-03-27T16:00:00+08:00"},
+	}
+
+	out, err := collectRoomFindResults(slots, 2, func(slot roomFindSlot) ([]*roomFindSuggestion, error) {
+		if strings.HasPrefix(slot.Start, "2026-03-27T14") {
+			return []*roomFindSuggestion{{RoomID: "rm_1", RoomName: "Room A"}}, nil
+		}
+		return nil, nil
+	})
+	if err != nil {
+		t.Fatalf("collectRoomFindResults returned error: %v", err)
+	}
+	if len(out.TimeSlots) != 2 {
+		t.Fatalf("expected 2 time slots, got %d", len(out.TimeSlots))
+	}
+
+	for _, ts := range out.TimeSlots {
+		if ts.MeetingRooms == nil {
+			t.Fatalf("meeting_rooms should be non-nil for slot %s", ts.Start)
+		}
+		switch {
+		case strings.HasPrefix(ts.Start, "2026-03-27T14"):
+			if len(ts.MeetingRooms) != 1 {
+				t.Fatalf("expected 1 room for first slot, got %d", len(ts.MeetingRooms))
+			}
+			if ts.Hint != "" {
+				t.Fatalf("non-empty slot should not carry hint, got %q", ts.Hint)
+			}
+		case strings.HasPrefix(ts.Start, "2026-03-27T15"):
+			if len(ts.MeetingRooms) != 0 {
+				t.Fatalf("expected 0 rooms for empty slot, got %d", len(ts.MeetingRooms))
+			}
+			if ts.Hint == "" {
+				t.Fatal("empty slot should carry a hint explaining the filters")
+			}
+		}
+	}
+
+	emptySlot := out.TimeSlots[0]
+	if !strings.HasPrefix(emptySlot.Start, "2026-03-27T15") {
+		emptySlot = out.TimeSlots[1]
+	}
+	raw, err := json.Marshal(emptySlot)
+	if err != nil {
+		t.Fatalf("marshal empty slot: %v", err)
+	}
+	if !strings.Contains(string(raw), `"meeting_rooms":[]`) {
+		t.Fatalf("expected meeting_rooms:[] in JSON, got %s", raw)
+	}
+	if !strings.Contains(string(raw), `"hint"`) {
+		t.Fatalf("expected hint field in JSON, got %s", raw)
+	}
+}

shortcuts/calendar/calendar_search_event.go

@@ -0,0 +1,331 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// calendar +search-event — search calendar events by keyword, time range, and attendees
+
+package calendar
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	defaultSearchEventPageSize = 20
+	maxSearchEventPageSize     = 30
+)
+
+// searchEventTimeRange represents the time range filter for search_event API.
+type searchEventTimeRange struct {
+	StartTime string `json:"start_time,omitempty"`
+	EndTime   string `json:"end_time,omitempty"`
+}
+
+// searchEventFilter represents the filter object for the search_event API request.
+type searchEventFilter struct {
+	AttendeeUserIDs []string              `json:"attendee_user_ids,omitempty"`
+	AttendeeChatIDs []string              `json:"attendee_chat_ids,omitempty"`
+	MeetingRoomIDs  []string              `json:"meeting_room_ids,omitempty"`
+	TimeRange       *searchEventTimeRange `json:"time_range,omitempty"`
+}
+
+// searchEventRequestBody is the request body for the search_event API.
+type searchEventRequestBody struct {
+	Query  string             `json:"query"`
+	Filter *searchEventFilter `json:"filter,omitempty"`
+}
+
+// searchEventTimeInfo represents start/end time info in the search result.
+type searchEventTimeInfo struct {
+	Date     string `json:"date,omitempty"`
+	DateTime string `json:"date_time,omitempty"`
+	Timezone string `json:"timezone,omitempty"`
+}
+
+// searchEventItem represents a single event in the search result output.
+type searchEventItem struct {
+	EventID  string               `json:"event_id"`
+	Summary  string               `json:"summary"`
+	Start    *searchEventTimeInfo `json:"start,omitempty"`
+	End      *searchEventTimeInfo `json:"end,omitempty"`
+	IsAllDay bool                 `json:"is_all_day,omitempty"`
+	AppLink  string               `json:"app_link,omitempty"`
+}
+
+// searchEventOutput is the structured output for +search-event.
+type searchEventOutput struct {
+	CalendarID string            `json:"calendar_id"`
+	Items      []searchEventItem `json:"items"`
+	HasMore    bool              `json:"has_more"`
+	PageToken  string            `json:"page_token"`
+}
+
+// parseSearchEventTimeRange parses --start / --end into RFC3339 strings.
+// When only one side is provided, the other defaults to the same day's
+// boundary (start → end-of-day, end → start-of-day).
+func parseSearchEventTimeRange(runtime *common.RuntimeContext) (string, string, error) {
+	startInput := strings.TrimSpace(runtime.Str("start"))
+	endInput := strings.TrimSpace(runtime.Str("end"))
+	if startInput == "" && endInput == "" {
+		return "", "", nil
+	}
+
+	var startSec, endSec int64
+
+	if startInput != "" {
+		ts, err := common.ParseTime(startInput)
+		if err != nil {
+			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start: %v", err).WithParam("--start")
+		}
+		startSec, _ = strconv.ParseInt(ts, 10, 64)
+	}
+	if endInput != "" {
+		ts, err := common.ParseTime(endInput, "end")
+		if err != nil {
+			return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
+		}
+		endSec, _ = strconv.ParseInt(ts, 10, 64)
+	}
+
+	if startInput == "" {
+		t := time.Unix(endSec, 0).In(time.Local)
+		startSec = time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, t.Location()).Unix()
+	}
+	if endInput == "" {
+		t := time.Unix(startSec, 0).In(time.Local)
+		endSec = time.Date(t.Year(), t.Month(), t.Day(), 23, 59, 59, 0, t.Location()).Unix()
+	}
+
+	if startSec > endSec {
+		return "", "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--start must be before --end").WithParam("--start")
+	}
+
+	return time.Unix(startSec, 0).Format(time.RFC3339), time.Unix(endSec, 0).Format(time.RFC3339), nil
+}
+
+// buildSearchEventFilter builds the filter object for the search_event API.
+func buildSearchEventFilter(runtime *common.RuntimeContext, startTime, endTime string) *searchEventFilter {
+	attendeeIDs := common.SplitCSV(runtime.Str("attendee-ids"))
+
+	var userIDs, chatIDs, roomIDs []string
+	for _, id := range attendeeIDs {
+		switch {
+		case strings.HasPrefix(id, "ou_"):
+			userIDs = append(userIDs, id)
+		case strings.HasPrefix(id, "oc_"):
+			chatIDs = append(chatIDs, id)
+		case strings.HasPrefix(id, "omm_"):
+			roomIDs = append(roomIDs, id)
+		default:
+			userIDs = append(userIDs, id)
+		}
+	}
+
+	var tr *searchEventTimeRange
+	if startTime != "" || endTime != "" {
+		tr = &searchEventTimeRange{StartTime: startTime, EndTime: endTime}
+	}
+
+	if len(userIDs) == 0 && len(chatIDs) == 0 && len(roomIDs) == 0 && tr == nil {
+		return nil
+	}
+	return &searchEventFilter{
+		AttendeeUserIDs: userIDs,
+		AttendeeChatIDs: chatIDs,
+		MeetingRoomIDs:  roomIDs,
+		TimeRange:       tr,
+	}
+}
+
+// extractTimeInfo extracts time info from a meta_data start/end map.
+func extractTimeInfo(m map[string]any) *searchEventTimeInfo {
+	if m == nil {
+		return nil
+	}
+	info := &searchEventTimeInfo{}
+	if v, ok := m["date"].(string); ok && v != "" {
+		info.Date = v
+	}
+	if v, ok := m["date_time"].(string); ok && v != "" {
+		info.DateTime = v
+	}
+	if v, ok := m["timezone"].(string); ok && v != "" {
+		info.Timezone = v
+	}
+	if info.Date == "" && info.DateTime == "" {
+		return nil
+	}
+	return info
+}
+
+// CalendarSearchEvent searches calendar events by keyword, time range, and attendees.
+var CalendarSearchEvent = common.Shortcut{
+	Service:     "calendar",
+	Command:     "+search-event",
+	Description: "Search calendar events by keyword, time range, and attendees",
+	Risk:        "read",
+	Scopes:      []string{"calendar:calendar.event:read"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "calendar-id", Desc: "calendar ID (default: primary)"},
+		{Name: "query", Desc: "search keyword"},
+		{Name: "attendee-ids", Desc: "attendee IDs, comma-separated (supports user ou_, chat oc_, room omm_)"},
+		{Name: "start", Desc: "search time range start (ISO 8601 or YYYY-MM-DD)"},
+		{Name: "end", Desc: "search time range end (ISO 8601 or YYYY-MM-DD)"},
+		{Name: "page-token", Desc: "page token for next page"},
+		{Name: "page-size", Default: "20", Desc: "page size, 1-30 (default 20)"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := rejectCalendarAutoBotFallback(runtime); err != nil {
+			return err
+		}
+		if _, _, err := parseSearchEventTimeRange(runtime); err != nil {
+			return err
+		}
+		if _, err := common.ValidatePageSizeTyped(runtime, "page-size", defaultSearchEventPageSize, 1, maxSearchEventPageSize); err != nil {
+			return err
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		calendarID := runtime.Str("calendar-id")
+		if calendarID == "" {
+			calendarID = "<primary>"
+		}
+		return common.NewDryRunAPI().
+			POST(fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/search_event", calendarID)).
+			Set("calendar_id", calendarID)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		calendarID := strings.TrimSpace(runtime.Str("calendar-id"))
+		if calendarID == "" {
+			calendarID = PrimaryCalendarIDStr
+		}
+
+		startTime, endTime, err := parseSearchEventTimeRange(runtime)
+		if err != nil {
+			return err
+		}
+
+		// Build request body — always send query (even if empty)
+		body := &searchEventRequestBody{
+			Query: strings.TrimSpace(runtime.Str("query")),
+		}
+		if filter := buildSearchEventFilter(runtime, startTime, endTime); filter != nil {
+			body.Filter = filter
+		}
+
+		// Build query params
+		params := map[string]any{}
+		pageSize, _ := strconv.Atoi(strings.TrimSpace(runtime.Str("page-size")))
+		if pageSize <= 0 {
+			pageSize = defaultSearchEventPageSize
+		}
+		params["page_size"] = strconv.Itoa(pageSize)
+		if pt := strings.TrimSpace(runtime.Str("page-token")); pt != "" {
+			params["page_token"] = pt
+		}
+
+		data, err := runtime.CallAPITyped("POST",
+			fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/search_event", validate.EncodePathSegment(calendarID)),
+			params, body)
+		if err != nil {
+			return err
+		}
+		if data == nil {
+			data = map[string]any{}
+		}
+
+		items := common.GetSlice(data, "items")
+		hasMore, _ := data["has_more"].(bool)
+		pageToken, _ := data["page_token"].(string)
+
+		// Transform items to structured output
+		outItems := make([]searchEventItem, 0, len(items))
+		for _, raw := range items {
+			item, _ := raw.(map[string]any)
+			if item == nil {
+				continue
+			}
+			meta, _ := item["meta_data"].(map[string]any)
+			out := searchEventItem{}
+			if meta != nil {
+				if v, ok := meta["event_id"].(string); ok {
+					out.EventID = v
+				}
+				if v, ok := meta["summary"].(string); ok {
+					out.Summary = v
+				}
+				if v, ok := meta["is_all_day"].(bool); ok {
+					out.IsAllDay = v
+				}
+				if v, ok := meta["app_link"].(string); ok {
+					out.AppLink = v
+				}
+				if start, ok := meta["start"].(map[string]any); ok {
+					out.Start = extractTimeInfo(start)
+				}
+				if end, ok := meta["end"].(map[string]any); ok {
+					out.End = extractTimeInfo(end)
+				}
+			}
+			outItems = append(outItems, out)
+		}
+
+		outData := searchEventOutput{
+			CalendarID: calendarID,
+			Items:      outItems,
+			HasMore:    hasMore,
+			PageToken:  pageToken,
+		}
+
+		runtime.OutFormat(outData, &output.Meta{Count: len(outItems)}, func(w io.Writer) {
+			if len(outItems) == 0 {
+				fmt.Fprintln(w, "No events found.")
+				return
+			}
+			var rows []map[string]interface{}
+			for _, item := range outItems {
+				row := map[string]interface{}{
+					"event_id": item.EventID,
+					"summary":  common.TruncateStr(item.Summary, 40),
+				}
+				if item.Start != nil {
+					if item.Start.DateTime != "" {
+						row["start"] = item.Start.DateTime
+					} else if item.Start.Date != "" {
+						row["start"] = item.Start.Date
+					}
+				}
+				if item.End != nil {
+					if item.End.DateTime != "" {
+						row["end"] = item.End.DateTime
+					} else if item.End.Date != "" {
+						row["end"] = item.End.Date
+					}
+				}
+				if item.IsAllDay {
+					row["is_all_day"] = true
+				}
+				rows = append(rows, row)
+			}
+			output.PrintTable(w, rows)
+			fmt.Fprintf(w, "\n%d event(s) found\n", len(outItems))
+		})
+
+		if hasMore && runtime.Format != "json" && runtime.Format != "" {
+			fmt.Fprintf(runtime.IO().Out, "\n(more available, page_token: %s)\n", pageToken)
+		}
+		return nil
+	},
+}

shortcuts/calendar/calendar_test.go

@@ -2234,10 +2234,10 @@ func TestResolveStartEnd_ExplicitValues(t *testing.T) {
 // Shortcuts() registration test
 // ---------------------------------------------------------------------------
 
-func TestShortcuts_Returns7(t *testing.T) {
+func TestShortcuts_Returns9(t *testing.T) {
 	shortcuts := Shortcuts()
-	if len(shortcuts) != 7 {
-		t.Fatalf("expected 7 shortcuts, got %d", len(shortcuts))
+	if len(shortcuts) != 9 {
+		t.Fatalf("expected 9 shortcuts, got %d", len(shortcuts))
 	}
 
 	names := map[string]bool{}

shortcuts/calendar/errors.go

@@ -42,3 +42,30 @@ func withParam(err error, flag string) error {
 	}
 	return err
 }
+
+// unwrapCalendarAPIError returns a user-facing message extracted from a
+// calendar business-domain *errs.APIError, or "" when the error is not an
+// APIError or its Code is not specialized here. Callers should fall back to
+// err.Error() on "".
+//
+// Today it handles:
+//   - 190014 (invalid_parameters): returns Problem.Hint, which carries the
+//     server-supplied field-level detail (e.g. "end_time should be later
+//     than start_time") lifted by errclass.BuildAPIError.
+//
+// Add additional 19xxxx codes here as they become worth surfacing — keep this
+// the single switch site so call sites stay readable.
+func unwrapCalendarAPIError(err error) string {
+	if err == nil {
+		return ""
+	}
+	var ae *errs.APIError
+	if !errors.As(err, &ae) {
+		return ""
+	}
+	switch ae.Code {
+	case 190014:
+		return ae.Hint
+	}
+	return ""
+}

shortcuts/calendar/errors_attribution_test.go

@@ -240,3 +240,62 @@ func TestParseCalendarAttendeeIDs_Valid(t *testing.T) {
 		t.Errorf("dedup/trim failed: got %v", ids)
 	}
 }
+
+// ---------------------------------------------------------------------------
+// unwrapCalendarAPIError helper
+// ---------------------------------------------------------------------------
+
+func TestUnwrapCalendarAPIError_NilReturnsEmpty(t *testing.T) {
+	if got := unwrapCalendarAPIError(nil); got != "" {
+		t.Errorf("nil err should return empty string, got %q", got)
+	}
+}
+
+func TestUnwrapCalendarAPIError_NonAPIErrorReturnsEmpty(t *testing.T) {
+	// Validation, internal, and plain errors are not calendar API business
+	// errors; the helper must signal "no specialization" so callers fall back.
+	cases := []error{
+		errs.NewValidationError(errs.SubtypeInvalidArgument, "bad input"),
+		errs.NewInternalError(errs.SubtypeSDKError, "io failure"),
+		errors.New("plain error"),
+	}
+	for _, e := range cases {
+		if got := unwrapCalendarAPIError(e); got != "" {
+			t.Errorf("unwrapCalendarAPIError(%T) = %q, want empty", e, got)
+		}
+	}
+}
+
+func TestUnwrapCalendarAPIError_Code190014_ReturnsHint(t *testing.T) {
+	ae := errs.NewAPIError(errs.SubtypeInvalidParameters, "invalid params").
+		WithCode(190014).
+		WithHint("end_time should be later than start_time")
+	got := unwrapCalendarAPIError(ae)
+	if got != "end_time should be later than start_time" {
+		t.Errorf("expected lifted hint, got %q", got)
+	}
+}
+
+func TestUnwrapCalendarAPIError_Code190014_WrappedStillResolves(t *testing.T) {
+	// withStepContext wraps the typed error but errors.As must still find it.
+	inner := errs.NewAPIError(errs.SubtypeInvalidParameters, "invalid params").
+		WithCode(190014).
+		WithHint("calendar_id is required")
+	wrapped := withStepContext(inner, "while fetching meeting info for %s", "evt_x")
+	got := unwrapCalendarAPIError(wrapped)
+	if !strings.Contains(got, "calendar_id is required") {
+		t.Errorf("expected wrapped 190014 to surface hint, got %q", got)
+	}
+}
+
+func TestUnwrapCalendarAPIError_UnhandledCodeReturnsEmpty(t *testing.T) {
+	// An APIError carrying a code that isn't specialized here should return
+	// "" so callers fall back to err.Error() — keeps the helper conservative
+	// while we add 19xxxx codes incrementally.
+	ae := errs.NewAPIError(errs.SubtypeInvalidParameters, "some other error").
+		WithCode(190099).
+		WithHint("ignore me")
+	if got := unwrapCalendarAPIError(ae); got != "" {
+		t.Errorf("unhandled code should return empty, got %q", got)
+	}
+}

shortcuts/calendar/shortcuts.go

@@ -15,5 +15,7 @@ func Shortcuts() []common.Shortcut {
 		CalendarRoomFind,
 		CalendarRsvp,
 		CalendarSuggestion,
+		CalendarMeeting,
+		CalendarSearchEvent,
 	}
 }

shortcuts/common/artifact_path.go

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 // This file defines artifact-path conventions shared between
-// `minutes +download` and `vc +notes`. Callers outside those two shortcuts
+// `minutes +download` and `minutes +detail`. Callers outside those two shortcuts
 // should not take a dependency on these symbols.
 
 package common

shortcuts/doc/docs_create_test.go

@@ -90,7 +90,6 @@ func TestDocsCreateV2BotAutoGrantSkippedWithoutCurrentUser(t *testing.T) {
 
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
-		"--api-version", "v2",
 		"--content", "<title>内容</title><p>正文</p>",
 		"--as", "bot",
 	})
@@ -125,7 +124,6 @@ func TestDocsCreateV2UserSkipsPermissionGrantAugmentation(t *testing.T) {
 
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
-		"--api-version", "v2",
 		"--content", "<title>内容</title><p>正文</p>",
 		"--as", "user",
 	})
@@ -163,7 +161,6 @@ func TestDocsCreateV2BotAutoGrantFailureDoesNotFailCreate(t *testing.T) {
 
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
-		"--api-version", "v2",
 		"--content", "<title>内容</title><p>正文</p>",
 		"--as", "bot",
 	})
@@ -201,7 +198,6 @@ func TestDocsCreateV2FallbackURLWhenBackendOmitsIt(t *testing.T) {
 
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
-		"--api-version", "v2",
 		"--content", "<title>内容</title><p>正文</p>",
 		"--as", "user",
 	})
@@ -233,7 +229,6 @@ func TestDocsCreateV2PreservesBackendURL(t *testing.T) {
 
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
-		"--api-version", "v2",
 		"--content", "<title>内容</title><p>正文</p>",
 		"--as", "user",
 	})
@@ -248,7 +243,7 @@ func TestDocsCreateV2PreservesBackendURL(t *testing.T) {
 	}
 }
 
-func TestDocsCreateAPIVersionV1StillUsesV2Endpoint(t *testing.T) {
+func TestDocsCreateAPIVersionCompatFlagIsIgnored(t *testing.T) {
 	t.Parallel()
 
 	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
@@ -262,7 +257,7 @@ func TestDocsCreateAPIVersionV1StillUsesV2Endpoint(t *testing.T) {
 
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
-		"--api-version", "v1",
+		"--api-version", "legacy",
 		"--content", "<title>项目计划</title>",
 		"--as", "user",
 	})

shortcuts/doc/docs_fetch_v2_test.go

@@ -507,10 +507,10 @@ func TestDocsFetchDryRunDefaultsToV2Endpoint(t *testing.T) {
 	}
 }
 
-func TestDocsFetchAPIVersionV1StillUsesV2Endpoint(t *testing.T) {
+func TestDocsFetchAPIVersionCompatFlagIsIgnored(t *testing.T) {
 	t.Parallel()
 
-	runtime := newFetchShortcutTestRuntime(t, "v1", nil)
+	runtime := newFetchShortcutTestRuntime(t, "legacy", nil)
 	if err := validateFetchV2(context.Background(), runtime); err != nil {
 		t.Fatalf("validateFetchV2() error = %v", err)
 	}

shortcuts/doc/docs_update_test.go

@@ -34,8 +34,8 @@ func TestValidCommandsV2(t *testing.T) {
 	}
 }
 
-func TestDocsUpdateDryRunAcceptsDeprecatedAPIVersionValues(t *testing.T) {
-	for _, apiVersion := range []string{"v1", "v2"} {
+func TestDocsUpdateDryRunIgnoresAPIVersionCompatFlag(t *testing.T) {
+	for _, apiVersion := range []string{"v1", "v2", "legacy"} {
 		t.Run(apiVersion, func(t *testing.T) {
 			t.Parallel()
 

shortcuts/doc/v2_only.go

@@ -17,9 +17,9 @@ type docsLegacyFlag struct {
 
 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",
+		Name:   "api-version",
+		Desc:   "deprecated compatibility flag; ignored by docs shortcuts",
+		Hidden: true,
 	}
 }
 
@@ -54,7 +54,7 @@ func docsLegacyFlagDefinitions(flags []docsLegacyFlag) []common.Flag {
 	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",
+			Desc:   "deprecated compatibility flag; run `lark-cli skills read lark-doc` for the current CLI skill",
 			Hidden: true,
 		})
 	}
@@ -62,12 +62,6 @@ func docsLegacyFlagDefinitions(flags []docsLegacyFlag) []common.Flag {
 }
 
 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", "--api-version")
-	}
-
 	var used []string
 	var replacements []string
 	for _, flag := range legacyFlags {

shortcuts/doc/v2_only_test.go

@@ -11,8 +11,8 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func TestValidateDocsV2OnlyAllowsDefaultAndDeprecatedAPIVersionValues(t *testing.T) {
-	for _, apiVersion := range []string{"", "v1", "v2"} {
+func TestValidateDocsV2OnlyIgnoresAPIVersionValues(t *testing.T) {
+	for _, apiVersion := range []string{"", "v1", "v2", "v0", "legacy"} {
 		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 {
@@ -22,28 +22,6 @@ func TestValidateDocsV2OnlyAllowsDefaultAndDeprecatedAPIVersionValues(t *testing
 	}
 }
 
-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"}})

shortcuts/minutes/minutes_detail.go

@@ -0,0 +1,320 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// minutes +detail — query minute details with selective artifact flags
+
+package minutes
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const minutesDetailLogPrefix = "[minutes +detail]"
+
+// Error codes from the minutes API.
+const minutesDetailNoReadPermissionCode = 2091005
+
+var validMinuteTokenDetail = regexp.MustCompile(`^[a-z0-9]+$`)
+
+var scopesDetailMinuteTokens = []string{
+	"minutes:minutes.basic:read",
+	"minutes:minutes.artifacts:read",
+}
+
+// minuteDetailItem represents a single minute detail result.
+type minuteDetailItem struct {
+	MinuteToken string         `json:"minute_token"`
+	Title       string         `json:"title"`
+	NoteID      string         `json:"note_id"`
+	Artifacts   map[string]any `json:"artifacts,omitempty"`
+	Error       string         `json:"error,omitempty"`
+}
+
+// fetchMinuteDetail queries a single minute's metadata and selected artifacts.
+func fetchMinuteDetail(ctx context.Context, runtime *common.RuntimeContext, minuteToken string) *minuteDetailItem {
+	data, err := runtime.CallAPITyped(http.MethodGet,
+		fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)), nil, nil)
+	if err != nil {
+		result := &minuteDetailItem{MinuteToken: minuteToken}
+		if p, ok := errs.ProblemOf(err); ok && p.Code == minutesDetailNoReadPermissionCode {
+			result.Error = fmt.Sprintf("No read permission for minute %s. Ask the minute owner for minute file read permission", minuteToken)
+		} else {
+			result.Error = fmt.Sprintf("failed to query minute: %v", err)
+		}
+		return result
+	}
+
+	minute, _ := data["minute"].(map[string]any)
+	if minute == nil {
+		return &minuteDetailItem{MinuteToken: minuteToken, Error: "minute not found"}
+	}
+
+	result := &minuteDetailItem{MinuteToken: minuteToken}
+	if v, ok := minute["title"].(string); ok && v != "" {
+		result.Title = v
+	}
+	if v, ok := minute["note_id"].(string); ok && v != "" {
+		result.NoteID = v
+	}
+
+	// Fetch artifacts selectively based on flags
+	needSummary := runtime.Bool("summary")
+	needTodo := runtime.Bool("todo")
+	needChapter := runtime.Bool("chapter")
+	needTranscript := runtime.Bool("transcript")
+	needKeyword := runtime.Bool("keyword")
+
+	if needSummary || needTodo || needChapter || needTranscript || needKeyword {
+		artData, err := runtime.CallAPITyped(http.MethodGet,
+			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/artifacts", validate.EncodePathSegment(minuteToken)), nil, nil)
+		if err != nil {
+			fmt.Fprintf(runtime.IO().ErrOut, "%s failed to fetch artifacts for %s: %v\n", minutesDetailLogPrefix, minuteToken, err)
+		} else {
+			artifacts := make(map[string]any)
+			if needSummary {
+				if v, ok := artData["summary"].(string); ok && v != "" {
+					artifacts["summary"] = v
+				} else {
+					artifacts["summary"] = ""
+				}
+			}
+			if needTodo {
+				if v, ok := artData["minute_todos"].([]any); ok && len(v) > 0 {
+					artifacts["todos"] = v
+				} else {
+					artifacts["todos"] = []any{}
+				}
+			}
+			if needChapter {
+				if v, ok := artData["minute_chapters"].([]any); ok && len(v) > 0 {
+					artifacts["chapters"] = v
+				} else {
+					artifacts["chapters"] = []any{}
+				}
+			}
+			if needKeyword {
+				if v, ok := artData["keywords"].([]any); ok && len(v) > 0 {
+					artifacts["keywords"] = v
+				} else {
+					artifacts["keywords"] = []any{}
+				}
+			}
+			if needTranscript {
+				if v, ok := artData["transcript"].(string); ok && v != "" {
+					if path := saveDetailTranscript(runtime, minuteToken, result.Title, []byte(v)); path != "" {
+						artifacts["transcript_file"] = path
+					} else {
+						artifacts["transcript_file"] = ""
+					}
+				} else {
+					artifacts["transcript_file"] = ""
+				}
+			}
+			result.Artifacts = artifacts
+		}
+	}
+
+	return result
+}
+
+// saveDetailTranscript persists transcript bytes to the canonical artifact path.
+// With --output-dir, transcripts land under <output-dir>/artifact-<title>-<token>/
+// to mirror the legacy `vc +notes` layout. Otherwise falls back to the default
+// ./minutes/<token>/ shared with `minutes +download`.
+func saveDetailTranscript(runtime *common.RuntimeContext, minuteToken, title string, content []byte) string {
+	errOut := runtime.IO().ErrOut
+	var dirName string
+	if outDir := runtime.Str("output-dir"); outDir != "" {
+		dirName = filepath.Join(outDir, sanitizeDetailDirName(title, minuteToken))
+	} else {
+		dirName = common.DefaultMinuteArtifactDir(minuteToken)
+	}
+	transcriptPath := filepath.Join(dirName, common.DefaultTranscriptFileName)
+
+	if !runtime.Bool("overwrite") {
+		if _, statErr := runtime.FileIO().Stat(transcriptPath); statErr == nil {
+			fmt.Fprintf(errOut, "%s transcript already exists: %s (use --overwrite to replace)\n", minutesDetailLogPrefix, transcriptPath)
+			return transcriptPath
+		}
+	}
+
+	fmt.Fprintf(errOut, "%s writing transcript: %s\n", minutesDetailLogPrefix, transcriptPath)
+	if _, err := runtime.FileIO().Save(transcriptPath, fileio.SaveOptions{}, bytes.NewReader(content)); err != nil {
+		fmt.Fprintf(errOut, "%s failed to write transcript: %v\n", minutesDetailLogPrefix, err)
+		return ""
+	}
+	return transcriptPath
+}
+
+// sanitizeDetailDirName generates a filesystem-safe directory name using title
+// and minuteToken for uniqueness. Mirrors the layout produced by `vc +notes`
+// so both shortcuts write artifacts to identical paths under --output-dir.
+func sanitizeDetailDirName(title, minuteToken string) string {
+	const maxLen = 200
+	replacer := strings.NewReplacer(
+		"/", "_", "\\", "_", ":", "_", "*", "_", "?", "_",
+		"\"", "_", "<", "_", ">", "_", "|", "_",
+		"\n", "_", "\r", "_", "\t", "_", "\x00", "_",
+	)
+	safe := replacer.Replace(strings.TrimSpace(title))
+	safe = strings.Trim(safe, ".")
+	if len(safe) > maxLen {
+		safe = safe[:maxLen]
+	}
+	if safe == "" {
+		return fmt.Sprintf("artifact-%s", minuteToken)
+	}
+	return fmt.Sprintf("artifact-%s-%s", safe, minuteToken)
+}
+
+// MinutesDetail queries minute details with selective artifact flags.
+var MinutesDetail = common.Shortcut{
+	Service:     "minutes",
+	Command:     "+detail",
+	Description: "Query minute details with selective artifact flags (summary, todo, chapter, transcript, keyword)",
+	Risk:        "read",
+	Scopes:      []string{"minutes:minutes.basic:read", "minutes:minutes.artifacts:read"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "minute-tokens", Desc: "minute tokens, comma-separated for batch", Required: true},
+		{Name: "summary", Type: "bool", Desc: "include summary"},
+		{Name: "todo", Type: "bool", Desc: "include todos"},
+		{Name: "chapter", Type: "bool", Desc: "include chapters"},
+		{Name: "transcript", Type: "bool", Desc: "include transcript (saved to file)"},
+		{Name: "keyword", Type: "bool", Desc: "include keywords"},
+		{Name: "output-dir", Desc: "output directory for transcript files (default: ./minutes/{minute_token}/)"},
+		{Name: "overwrite", Type: "bool", Desc: "overwrite existing transcript files"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		tokens := common.SplitCSV(runtime.Str("minute-tokens"))
+		const maxBatchSize = 50
+		if len(tokens) > maxBatchSize {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--minute-tokens: too many tokens (%d), maximum is %d", len(tokens), maxBatchSize).WithParam("--minute-tokens")
+		}
+		for _, token := range tokens {
+			if !validMinuteTokenDetail.MatchString(token) {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid minute token %q: must contain only lowercase alphanumeric characters", token).WithParam("--minute-tokens")
+			}
+		}
+		if outDir := runtime.Str("output-dir"); outDir != "" {
+			if err := common.ValidateSafePathTyped(runtime.FileIO(), outDir); err != nil {
+				return err
+			}
+		}
+		// dynamic scope check
+		result, err := runtime.Factory.Credential.ResolveToken(ctx, credential.NewTokenSpec(runtime.As(), runtime.Config.AppID))
+		if err == nil && result != nil && result.Scopes != "" {
+			if missing := auth.MissingScopes(result.Scopes, scopesDetailMinuteTokens); 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 nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		tokens := runtime.Str("minute-tokens")
+		d := common.NewDryRunAPI().
+			GET("/open-apis/minutes/v1/minutes/{minute_token}").
+			Set("minute_tokens", common.SplitCSV(tokens))
+
+		if runtime.Bool("summary") || runtime.Bool("todo") || runtime.Bool("chapter") || runtime.Bool("transcript") || runtime.Bool("keyword") {
+			d.GET("/open-apis/minutes/v1/minutes/{minute_token}/artifacts")
+		}
+		return d
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		errOut := runtime.IO().ErrOut
+		minuteTokens := common.SplitCSV(runtime.Str("minute-tokens"))
+		results := make([]*minuteDetailItem, 0, len(minuteTokens))
+
+		const batchDelay = 100 * time.Millisecond
+		fmt.Fprintf(errOut, "%s querying %d minute_token(s)\n", minutesDetailLogPrefix, len(minuteTokens))
+		for i, token := range minuteTokens {
+			if err := ctx.Err(); err != nil {
+				return err
+			}
+			if i > 0 {
+				time.Sleep(batchDelay)
+			}
+			fmt.Fprintf(errOut, "%s querying minute_token=%s ...\n", minutesDetailLogPrefix, token)
+			results = append(results, fetchMinuteDetail(ctx, runtime, token))
+		}
+
+		successCount := 0
+		for _, r := range results {
+			if r.Error == "" {
+				successCount++
+			}
+		}
+		fmt.Fprintf(errOut, "%s done: %d total, %d succeeded, %d failed\n", minutesDetailLogPrefix, len(results), successCount, len(results)-successCount)
+
+		if successCount == 0 && len(results) > 0 {
+			return runtime.OutPartialFailure(map[string]any{"minutes": results}, &output.Meta{Count: len(results)})
+		}
+
+		outData := map[string]any{"minutes": results}
+		runtime.OutFormat(outData, &output.Meta{Count: len(results)}, func(w io.Writer) {
+			if len(results) == 0 {
+				fmt.Fprintln(w, "No minutes.")
+				return
+			}
+			var rows []map[string]interface{}
+			for _, r := range results {
+				row := map[string]interface{}{"minute_token": r.MinuteToken}
+				if r.Error != "" {
+					row["status"] = "FAIL"
+					row["error"] = r.Error
+				} else {
+					row["status"] = "OK"
+					row["title"] = r.Title
+					row["note_id"] = r.NoteID
+					if len(r.Artifacts) > 0 {
+						var parts []string
+						if _, ok := r.Artifacts["summary"]; ok {
+							parts = append(parts, "summary")
+						}
+						if _, ok := r.Artifacts["todos"]; ok {
+							parts = append(parts, "todo")
+						}
+						if _, ok := r.Artifacts["chapters"]; ok {
+							parts = append(parts, "chapter")
+						}
+						if _, ok := r.Artifacts["keywords"]; ok {
+							parts = append(parts, "keyword")
+						}
+						if _, ok := r.Artifacts["transcript_file"]; ok {
+							parts = append(parts, "transcript")
+						}
+						if len(parts) > 0 {
+							row["artifacts"] = strings.Join(parts, ", ")
+						}
+					}
+				}
+				rows = append(rows, row)
+			}
+			output.PrintTable(w, rows)
+			fmt.Fprintf(w, "\n%d minute(s), %d succeeded, %d failed\n", len(results), successCount, len(results)-successCount)
+		})
+		return nil
+	},
+}

shortcuts/minutes/minutes_detail_test.go

@@ -0,0 +1,394 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+	"sync"
+	"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/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+var detailWarmOnce sync.Once
+
+func detailWarmTokenCache(t *testing.T) {
+	t.Helper()
+	detailWarmOnce.Do(func() {
+		f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+		reg.Register(&httpmock.Stub{
+			URL:  "/open-apis/test/v1/warm",
+			Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{}},
+		})
+		s := common.Shortcut{
+			Service:   "test",
+			Command:   "+warm",
+			AuthTypes: []string{"bot"},
+			Execute: func(_ context.Context, rctx *common.RuntimeContext) error {
+				_, err := rctx.CallAPITyped("GET", "/open-apis/test/v1/warm", nil, nil)
+				return err
+			},
+		}
+		parent := &cobra.Command{Use: "test"}
+		s.Mount(parent, f)
+		parent.SetArgs([]string{"+warm"})
+		parent.SilenceErrors = true
+		parent.SilenceUsage = true
+		parent.Execute()
+	})
+}
+
+func detailMountAndRun(t *testing.T, s common.Shortcut, args []string, f *cmdutil.Factory, stdout *bytes.Buffer) error {
+	t.Helper()
+	detailWarmTokenCache(t)
+	parent := &cobra.Command{Use: "minutes"}
+	s.Mount(parent, f)
+	parent.SetArgs(args)
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	if stdout != nil {
+		stdout.Reset()
+	}
+	return parent.Execute()
+}
+
+// ---------------------------------------------------------------------------
+// Validation tests
+// ---------------------------------------------------------------------------
+
+func detailMinuteGetStub(token, noteID, title string) *httpmock.Stub {
+	minute := map[string]interface{}{"title": title}
+	if noteID != "" {
+		minute["note_id"] = noteID
+	}
+	return &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/minutes/v1/minutes/" + token,
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"minute": minute},
+		},
+	}
+}
+
+func detailArtifactsStub(token, transcript string) *httpmock.Stub {
+	data := map[string]interface{}{
+		"summary":         "Test summary content",
+		"minute_todos":    []interface{}{map[string]interface{}{"content": "Buy milk"}},
+		"minute_chapters": []interface{}{map[string]interface{}{"title": "Intro", "summary_content": "Opening"}},
+		"keywords":        []interface{}{"budget", "roadmap"},
+	}
+	if transcript != "" {
+		data["transcript"] = transcript
+	}
+	return &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/minutes/v1/minutes/" + token + "/artifacts",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": data,
+		},
+	}
+}
+
+func TestDetail_Validation_MissingMinuteTokens(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for missing --minute-tokens")
+	}
+}
+
+func TestDetail_Validation_InvalidToken(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "INVALID!", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for invalid token")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if ve.Param != "--minute-tokens" {
+		t.Errorf("Param = %q, want --minute-tokens", ve.Param)
+	}
+}
+
+func TestDetail_Validation_BatchLimit(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	tokens := make([]string, 51)
+	for i := range tokens {
+		tokens[i] = fmt.Sprintf("tok%d", i)
+	}
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", strings.Join(tokens, ","), "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected batch limit error")
+	}
+	if !strings.Contains(err.Error(), "too many tokens") {
+		t.Errorf("expected 'too many tokens' error, got: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// DryRun tests
+// ---------------------------------------------------------------------------
+
+func TestDetail_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tok001", "--dry-run", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "/open-apis/minutes/v1/minutes/") {
+		t.Errorf("dry-run should show minutes API path, got: %s", stdout.String())
+	}
+}
+
+func TestDetail_DryRun_WithArtifactFlags(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tok001", "--summary", "--todo", "--dry-run", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "artifacts") {
+		t.Errorf("dry-run should show artifacts API path when artifact flags are set, got: %s", stdout.String())
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Execute tests with mocked HTTP
+// ---------------------------------------------------------------------------
+
+func TestDetail_Execute_BasicInfo(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("tokbasic", "", "Test Meeting"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokbasic", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	minutes, _ := data["minutes"].([]any)
+	if len(minutes) != 1 {
+		t.Fatalf("expected 1 minute, got %d", len(minutes))
+	}
+	m, _ := minutes[0].(map[string]any)
+	if m["minute_token"] != "tokbasic" {
+		t.Errorf("minute_token = %v, want tokbasic", m["minute_token"])
+	}
+	if m["title"] != "Test Meeting" {
+		t.Errorf("title = %v, want Test Meeting", m["title"])
+	}
+	noteID, hasNoteID := m["note_id"]
+	if !hasNoteID {
+		t.Error("note_id should always be present in output (even when empty)")
+	}
+	if noteID != "" {
+		t.Errorf("note_id should be empty string when minute has no note_id, got %v", noteID)
+	}
+}
+
+func TestDetail_Execute_WithSummaryAndTodo(t *testing.T) {
+	chdirForDetailTest(t)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("tokart", "note_art", "Artifact Meeting"))
+	reg.Register(detailArtifactsStub("tokart", ""))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokart", "--summary", "--todo", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	minutes, _ := data["minutes"].([]any)
+	if len(minutes) != 1 {
+		t.Fatalf("expected 1 minute, got %d", len(minutes))
+	}
+	m, _ := minutes[0].(map[string]any)
+	if m["note_id"] != "note_art" {
+		t.Errorf("note_id = %v, want note_art", m["note_id"])
+	}
+	arts, _ := m["artifacts"].(map[string]any)
+	if arts == nil {
+		t.Fatal("expected artifacts to be present")
+	}
+	if _, ok := arts["summary"]; !ok {
+		t.Error("expected summary in artifacts")
+	}
+	if _, ok := arts["todos"]; !ok {
+		t.Error("expected todos in artifacts")
+	}
+	// chapter and keywords should NOT be present since flags not set
+	if _, ok := arts["chapters"]; ok {
+		t.Error("chapters should not be present when --chapter not set")
+	}
+	if _, ok := arts["keywords"]; ok {
+		t.Error("keywords should not be present when --keyword not set")
+	}
+}
+
+func TestDetail_Execute_NoArtifactFlags(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("toknoart", "", "No Artifacts"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "toknoart", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	minutes, _ := data["minutes"].([]any)
+	if len(minutes) != 1 {
+		t.Fatalf("expected 1 minute, got %d", len(minutes))
+	}
+	m, _ := minutes[0].(map[string]any)
+	if _, ok := m["artifacts"]; ok {
+		t.Error("artifacts should not be present when no artifact flags set")
+	}
+}
+
+func TestDetail_Execute_Transcript(t *testing.T) {
+	chdirForDetailTest(t)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("toktrans", "", "Transcript Meeting"))
+	reg.Register(detailArtifactsStub("toktrans", "speaker1: hello world\n"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "toktrans", "--transcript", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Check transcript file was saved
+	wantPath := "minutes/toktrans/transcript.txt"
+	data, err := os.ReadFile(wantPath)
+	if err != nil {
+		t.Fatalf("expected file at %s: %v", wantPath, err)
+	}
+	if string(data) != "speaker1: hello world\n" {
+		t.Errorf("content mismatch: %q", string(data))
+	}
+}
+
+func TestDetail_Execute_Transcript_OutputDir(t *testing.T) {
+	chdirForDetailTest(t)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("tokod", "", "Output Dir Meeting"))
+	reg.Register(detailArtifactsStub("tokod", "alice: hi\n"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokod", "--transcript", "--output-dir", "custom_out", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Mirrors `minutes +detail --output-dir` layout: artifact-<title>-<token>/transcript.txt
+	wantPath := "custom_out/artifact-Output Dir Meeting-tokod/transcript.txt"
+	data, err := os.ReadFile(wantPath)
+	if err != nil {
+		t.Fatalf("expected file at %s: %v", wantPath, err)
+	}
+	if string(data) != "alice: hi\n" {
+		t.Errorf("content mismatch: %q", string(data))
+	}
+}
+
+func TestDetail_Validation_OutputDirEscape(t *testing.T) {
+	chdirForDetailTest(t)
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tok001", "--output-dir", "../escape", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for escaping output-dir")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+}
+
+func TestDetail_Execute_MinuteNotFound(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/minutes/v1/minutes/tokbad",
+		Body:   map[string]interface{}{"code": 2091004, "msg": "not found"},
+	})
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokbad", "--as", "user"}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Pure function tests
+// ---------------------------------------------------------------------------
+
+func TestValidMinuteTokenDetail(t *testing.T) {
+	tests := []struct {
+		token string
+		valid bool
+	}{
+		{"abc123", true},
+		{"obcnmgn1429t5xt9j82i1p3h", true},
+		{"INVALID!", false},
+		{"has-space", false},
+		{"", false},
+	}
+	for _, tt := range tests {
+		got := validMinuteTokenDetail.MatchString(tt.token)
+		if got != tt.valid {
+			t.Errorf("validMinuteTokenDetail(%q) = %v, want %v", tt.token, got, tt.valid)
+		}
+	}
+}
+
+// chdirForDetailTest switches cwd to a temp dir for the test.
+func chdirForDetailTest(t *testing.T) string {
+	t.Helper()
+	orig, err := os.Getwd()
+	if err != nil {
+		t.Fatalf("getwd: %v", err)
+	}
+	dir := t.TempDir()
+	if err := os.Chdir(dir); err != nil {
+		t.Fatalf("chdir: %v", err)
+	}
+	t.Cleanup(func() { os.Chdir(orig) })
+	return dir
+}

shortcuts/minutes/minutes_search.go

@@ -184,12 +184,6 @@ func minuteSearchAppLink(item map[string]interface{}) string {
 	return common.GetString(meta, "app_link")
 }
 
-// minuteSearchAvatar extracts the avatar URL from a search result item.
-func minuteSearchAvatar(item map[string]interface{}) string {
-	meta := common.GetMap(item, "meta_data")
-	return common.GetString(meta, "avatar")
-}
-
 // buildMinuteSearchRows converts API items into pretty output rows.
 func buildMinuteSearchRows(items []interface{}) []map[string]interface{} {
 	rows := make([]map[string]interface{}, 0, len(items))
@@ -203,12 +197,27 @@ func buildMinuteSearchRows(items []interface{}) []map[string]interface{} {
 			"display_info": common.TruncateStr(minuteSearchDisplayInfo(item), 40),
 			"description":  common.TruncateStr(minuteSearchDescription(item), 40),
 			"app_link":     common.TruncateStr(minuteSearchAppLink(item), 80),
-			"avatar":       common.TruncateStr(minuteSearchAvatar(item), 80),
 		})
 	}
 	return rows
 }
 
+// stripAvatarFromItems removes meta_data.avatar from each search item in place
+// so the structured output does not surface avatars to AI agents.
+func stripAvatarFromItems(items []interface{}) {
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		if item == nil {
+			continue
+		}
+		meta, _ := item["meta_data"].(map[string]interface{})
+		if meta == nil {
+			continue
+		}
+		delete(meta, "avatar")
+	}
+}
+
 // MinutesSearch searches minutes by keyword, owners, participants, and time range.
 var MinutesSearch = common.Shortcut{
 	Service:     "minutes",
@@ -298,13 +307,13 @@ var MinutesSearch = common.Shortcut{
 		}
 
 		items := minuteSearchItems(data)
+		stripAvatarFromItems(items)
 		hasMore, _ := data["has_more"].(bool)
 		pageToken, _ := data["page_token"].(string)
 		rows := buildMinuteSearchRows(items)
 
 		outData := map[string]interface{}{
 			"items":      items,
-			"total":      data["total"],
 			"has_more":   data["has_more"],
 			"page_token": data["page_token"],
 		}

shortcuts/minutes/minutes_search_test.go

@@ -526,7 +526,7 @@ func TestMinutesSearchExecuteRendersRowsAndMoreHint(t *testing.T) {
 	}
 
 	out := stdout.String()
-	for _, want := range []string{"minute_1", "周会摘要", "周会纪要", "https://meetings.feishu.cn/minutes/obcn123", "https://p3-lark-file.byteimg.com/img/xxxx.jpg", "next_token", "more available"} {
+	for _, want := range []string{"minute_1", "周会摘要", "周会纪要", "https://meetings.feishu.cn/minutes/obcn123", "next_token", "more available"} {
 		if !strings.Contains(out, want) {
 			t.Fatalf("output missing %q, got: %s", want, out)
 		}
@@ -672,7 +672,6 @@ func TestMinuteSearchFieldExtractors(t *testing.T) {
 		"meta_data": map[string]interface{}{
 			"description": "周会纪要",
 			"app_link":    "https://meetings.feishu.cn/minutes/obcn123",
-			"avatar":      "https://p3-lark-file.byteimg.com/img/xxxx.jpg",
 		},
 	}
 
@@ -688,9 +687,6 @@ func TestMinuteSearchFieldExtractors(t *testing.T) {
 	if got := minuteSearchAppLink(item); got != "https://meetings.feishu.cn/minutes/obcn123" {
 		t.Fatalf("minuteSearchAppLink() = %q", got)
 	}
-	if got := minuteSearchAvatar(item); got != "https://p3-lark-file.byteimg.com/img/xxxx.jpg" {
-		t.Fatalf("minuteSearchAvatar() = %q", got)
-	}
 }
 
 // TestMinuteSearchFieldExtractorsFallbacks verifies extractors keep working for alternate sample data.
@@ -703,7 +699,6 @@ func TestMinuteSearchFieldExtractorsFallbacks(t *testing.T) {
 		"meta_data": map[string]interface{}{
 			"description": "回退纪要",
 			"app_link":    "https://meetings.feishu.cn/minutes/fallback",
-			"avatar":      "https://p3-lark-file.byteimg.com/img/fallback.jpg",
 		},
 	}
 
@@ -716,9 +711,6 @@ func TestMinuteSearchFieldExtractorsFallbacks(t *testing.T) {
 	if got := minuteSearchAppLink(item); got != "https://meetings.feishu.cn/minutes/fallback" {
 		t.Fatalf("minuteSearchAppLink() = %q", got)
 	}
-	if got := minuteSearchAvatar(item); got != "https://p3-lark-file.byteimg.com/img/fallback.jpg" {
-		t.Fatalf("minuteSearchAvatar() = %q", got)
-	}
 }
 
 // TestMinuteSearchFieldExtractorsMissingMetaData verifies extractors fall back to empty values without metadata.
@@ -739,7 +731,32 @@ func TestMinuteSearchFieldExtractorsMissingMetaData(t *testing.T) {
 	if got := minuteSearchAppLink(item); got != "" {
 		t.Fatalf("minuteSearchAppLink() = %q, want empty", got)
 	}
-	if got := minuteSearchAvatar(item); got != "" {
-		t.Fatalf("minuteSearchAvatar() = %q, want empty", got)
+}
+
+// TestStripAvatarFromItems verifies the avatar field is removed from items in place.
+func TestStripAvatarFromItems(t *testing.T) {
+	t.Parallel()
+
+	items := []interface{}{
+		map[string]interface{}{
+			"token": "minute_1",
+			"meta_data": map[string]interface{}{
+				"description": "周会纪要",
+				"avatar":      "https://p3-lark-file.byteimg.com/img/xxxx.jpg",
+			},
+		},
+		nil,
+		map[string]interface{}{"token": "minute_no_meta"},
+	}
+
+	stripAvatarFromItems(items)
+
+	first, _ := items[0].(map[string]interface{})
+	meta, _ := first["meta_data"].(map[string]interface{})
+	if _, ok := meta["avatar"]; ok {
+		t.Fatalf("avatar should be stripped, got meta = %v", meta)
+	}
+	if meta["description"] != "周会纪要" {
+		t.Fatalf("description should be preserved, got %v", meta["description"])
 	}
 }

shortcuts/minutes/minutes_speaker_replace.go

@@ -25,12 +25,13 @@ var MinutesSpeakerReplace = common.Shortcut{
 	Command:     "+speaker-replace",
 	Description: "Replace a speaker in a minute's transcript (rebind from one user to another)",
 	Risk:        "write",
-	Scopes:      []string{"minutes:minutes:update"},
+	Scopes:      []string{"minutes:minutes:readonly", "minutes:minutes:update"},
 	AuthTypes:   []string{"user"},
 	HasFormat:   true,
 	Flags: []common.Flag{
 		{Name: "minute-token", Desc: "minute token", Required: true},
-		{Name: "from-user-id", Desc: "speaker to replace, must be an open_id starting with 'ou_'", Required: true},
+		{Name: "from-speaker-id", Desc: "speaker to replace: opaque speaker_id from transcript speakerlist API (do not pass display names)"},
+		{Name: "from-user-id", Desc: "deprecated: open_id of the speaker to replace; prefer --from-speaker-id", Hidden: true},
 		{Name: "to-user-id", Desc: "new speaker, must be an open_id starting with 'ou_'", Required: true},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -41,12 +42,10 @@ var MinutesSpeakerReplace = common.Shortcut{
 		if err := validate.ResourceName(minuteToken, "--minute-token"); err != nil {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--minute-token")
 		}
+		fromSpeakerID := strings.TrimSpace(runtime.Str("from-speaker-id"))
 		fromUserID := strings.TrimSpace(runtime.Str("from-user-id"))
-		if fromUserID == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--from-user-id is required").WithParam("--from-user-id")
-		}
-		if _, err := common.ValidateUserIDTyped("--from-user-id", fromUserID); err != nil {
-			return err
+		if fromSpeakerID == "" && fromUserID == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--from-speaker-id is required").WithParam("--from-speaker-id")
 		}
 		toUserID := strings.TrimSpace(runtime.Str("to-user-id"))
 		if toUserID == "" {
@@ -55,53 +54,93 @@ var MinutesSpeakerReplace = common.Shortcut{
 		if _, err := common.ValidateUserIDTyped("--to-user-id", toUserID); err != nil {
 			return err
 		}
-		if fromUserID == toUserID {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--from-user-id and --to-user-id must be different").WithParam("--to-user-id")
+		if fromSpeakerID == "" {
+			if _, err := common.ValidateUserIDTyped("--from-user-id", fromUserID); err != nil {
+				return err
+			}
+			if fromUserID == toUserID {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--from-user-id and --to-user-id must be different").WithParam("--to-user-id")
+			}
 		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
-		fromUserID := strings.TrimSpace(runtime.Str("from-user-id"))
-		toUserID := strings.TrimSpace(runtime.Str("to-user-id"))
-		return common.NewDryRunAPI().
-			PUT(fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken))).
-			Body(map[string]interface{}{
-				"minute_token": minuteToken,
-				"from_user_id": fromUserID,
-				"to_user_id":   toUserID,
-			})
+		dr := common.NewDryRunAPI()
+		if strings.TrimSpace(runtime.Str("from-speaker-id")) != "" && strings.TrimSpace(runtime.Str("from-user-id")) == "" {
+			dr.GET(minuteTranscriptSpeakerlistPath(minuteToken)).Desc("Resolve --from-speaker-id when it is a display name")
+		}
+		return dr.PUT(fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken))).
+			Body(buildSpeakerReplaceRequestBody(runtime))
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
-		fromUserID := strings.TrimSpace(runtime.Str("from-user-id"))
+		fromSpeakerInput := strings.TrimSpace(runtime.Str("from-speaker-id"))
 		toUserID := strings.TrimSpace(runtime.Str("to-user-id"))
 
-		body := map[string]interface{}{
-			"minute_token": minuteToken,
-			"from_user_id": fromUserID,
-			"to_user_id":   toUserID,
-		}
-
-		_, err := runtime.CallAPITyped(http.MethodPut,
-			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken)),
-			nil, body)
+		fromSpeakerID, fromUserID, err := resolveSpeakerReplaceFrom(runtime, minuteToken)
 		if err != nil {
-			return minutesSpeakerReplaceError(err, minuteToken, fromUserID)
+			return err
 		}
 
-		outData := map[string]interface{}{
-			"minute_token": minuteToken,
-			"from_user_id": fromUserID,
-			"to_user_id":   toUserID,
+		_, err = runtime.CallAPITyped(http.MethodPut,
+			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken)),
+			map[string]interface{}{"user_id_type": "open_id"}, buildSpeakerReplaceRequestBodyResolved(fromSpeakerID, fromUserID, toUserID))
+		if err != nil {
+			return minutesSpeakerReplaceError(err, minuteToken, speakerReplaceSourceLabel(fromSpeakerInput, fromSpeakerID, fromUserID))
 		}
 
-		runtime.OutFormat(outData, nil, nil)
+		runtime.OutFormat(buildSpeakerReplaceOutputData(fromSpeakerInput, minuteToken, fromSpeakerID, fromUserID, toUserID), nil, nil)
 		return nil
 	},
 }
 
-func minutesSpeakerReplaceError(err error, minuteToken, fromUserID string) error {
+func buildSpeakerReplaceRequestBody(runtime *common.RuntimeContext) map[string]interface{} {
+	fromSpeakerID := strings.TrimSpace(runtime.Str("from-speaker-id"))
+	fromUserID := strings.TrimSpace(runtime.Str("from-user-id"))
+	toUserID := strings.TrimSpace(runtime.Str("to-user-id"))
+	return buildSpeakerReplaceRequestBodyResolved(fromSpeakerID, fromUserID, toUserID)
+}
+
+func buildSpeakerReplaceRequestBodyResolved(fromSpeakerID, fromUserID, toUserID string) map[string]interface{} {
+	body := map[string]interface{}{
+		"to_user_id": toUserID,
+	}
+	if fromSpeakerID != "" {
+		body["from_speaker_id"] = fromSpeakerID
+	} else {
+		body["from_user_id"] = fromUserID
+	}
+	return body
+}
+
+func buildSpeakerReplaceOutputData(fromSpeakerInput, minuteToken, fromSpeakerID, fromUserID, toUserID string) map[string]interface{} {
+	out := map[string]interface{}{
+		"minute_token": minuteToken,
+		"to_user_id":   toUserID,
+	}
+	if fromSpeakerID != "" {
+		out["from_speaker_id"] = fromSpeakerID
+		if fromSpeakerInput != "" && fromSpeakerInput != fromSpeakerID {
+			out["from_speaker_input"] = fromSpeakerInput
+		}
+	} else {
+		out["from_user_id"] = fromUserID
+	}
+	return out
+}
+
+func speakerReplaceSourceLabel(fromSpeakerInput, fromSpeakerID, fromUserID string) string {
+	if fromSpeakerInput != "" {
+		return fromSpeakerInput
+	}
+	if fromSpeakerID != "" {
+		return fromSpeakerID
+	}
+	return fromUserID
+}
+
+func minutesSpeakerReplaceError(err error, minuteToken, sourceSpeaker string) error {
 	p, ok := errs.ProblemOf(err)
 	if !ok {
 		return err
@@ -112,8 +151,8 @@ func minutesSpeakerReplaceError(err error, minuteToken, fromUserID string) error
 		p.Hint = "Ask the minute owner for minute edit permission"
 	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."
+		p.Message = fmt.Sprintf("Speaker not found in minute %q: source speaker %q does not match an existing speaker in the transcript.", minuteToken, sourceSpeaker)
+		p.Hint = "Verify --from-speaker-id is a valid speaker_id or display name from the transcript; if multiple speakers share the same name, pass the exact speaker_id after reviewing their utterances."
 	}
 	return err
 }

shortcuts/minutes/minutes_speaker_replace_test.go

@@ -34,7 +34,7 @@ func TestMinutesSpeakerReplace_Validate(t *testing.T) {
 		{
 			name:    "missing from",
 			args:    []string{"+speaker-replace", "--minute-token", minutesSpeakerReplaceTestToken, "--to-user-id", "ou_b", "--as", "user"},
-			wantErr: "required flag(s) \"from-user-id\" not set",
+			wantErr: "--from-speaker-id is required",
 		},
 		{
 			name:    "missing to",
@@ -153,6 +153,129 @@ func TestMinutesSpeakerReplace_DryRun(t *testing.T) {
 	}
 }
 
+func TestMinutesSpeakerReplace_DryRun_ResolveFromSpeakerID(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	warmTokenCache(t)
+
+	err := mountAndRun(t, MinutesSpeakerReplace, []string{
+		"+speaker-replace",
+		"--minute-token", minutesSpeakerReplaceTestToken,
+		"--from-speaker-id", "说话人1",
+		"--to-user-id", "ou_new_speaker",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	if !strings.Contains(out, "GET") {
+		t.Errorf("expected GET for internal speaker list, got:\n%s", out)
+	}
+	if !strings.Contains(out, "/transcript/speakerlist") {
+		t.Errorf("expected speakerlist path, got:\n%s", out)
+	}
+	if !strings.Contains(out, "PUT") {
+		t.Errorf("expected PUT for speaker replace, got:\n%s", out)
+	}
+	if !strings.Contains(out, "ou_new_speaker") {
+		t.Errorf("expected to_user_id in body, got:\n%s", out)
+	}
+}
+
+func TestMinutesSpeakerReplace_Execute_ResolveFromSpeakerID(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	warmTokenCache(t)
+
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodGet,
+		URL:    "/open-apis/minutes/v1/minutes/" + minutesSpeakerReplaceTestToken + "/transcript/speakerlist",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"speakers": []interface{}{
+					map[string]interface{}{
+						"speaker_id": "ENCRYPTED_TOKEN_ABC",
+						"name":       "说话人1",
+					},
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: http.MethodPut,
+		URL:    "/open-apis/minutes/v1/minutes/" + minutesSpeakerReplaceTestToken + "/transcript/speaker",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRun(t, MinutesSpeakerReplace, []string{
+		"+speaker-replace",
+		"--minute-token", minutesSpeakerReplaceTestToken,
+		"--from-speaker-id", "说话人1",
+		"--to-user-id", "ou_new_speaker",
+		"--format", "json", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var envelope struct {
+		Data struct {
+			MinuteToken      string `json:"minute_token"`
+			FromSpeakerInput string `json:"from_speaker_input"`
+			FromSpeakerID    string `json:"from_speaker_id"`
+			ToUserID         string `json:"to_user_id"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("unmarshal stdout: %v", err)
+	}
+	if envelope.Data.FromSpeakerInput != "说话人1" {
+		t.Errorf("data.from_speaker_input = %q, want 说话人1", envelope.Data.FromSpeakerInput)
+	}
+	if envelope.Data.FromSpeakerID != "ENCRYPTED_TOKEN_ABC" {
+		t.Errorf("data.from_speaker_id = %q, want ENCRYPTED_TOKEN_ABC", envelope.Data.FromSpeakerID)
+	}
+}
+
+func TestMinutesSpeakerReplace_DryRun_FromSpeakerID(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	warmTokenCache(t)
+
+	err := mountAndRun(t, MinutesSpeakerReplace, []string{
+		"+speaker-replace",
+		"--minute-token", minutesSpeakerReplaceTestToken,
+		"--from-speaker-id", "ENCRYPTED_TOKEN_ABC",
+		"--to-user-id", "ou_new_speaker",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	if !strings.Contains(out, "GET") {
+		t.Errorf("expected GET for internal speaker list, got:\n%s", out)
+	}
+	if !strings.Contains(out, "from_speaker_id") || !strings.Contains(out, "ENCRYPTED_TOKEN_ABC") {
+		t.Errorf("expected from_speaker_id in body, got:\n%s", out)
+	}
+	if strings.Contains(out, "from_user_id") {
+		t.Errorf("from_speaker_id path should not send from_user_id, got:\n%s", out)
+	}
+	if !strings.Contains(out, "ou_new_speaker") {
+		t.Errorf("expected to_user_id in body, got:\n%s", out)
+	}
+}
+
 func TestMinutesSpeakerReplace_Execute(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
@@ -238,8 +361,8 @@ func TestMinutesSpeakerReplace_SpeakerNotFound(t *testing.T) {
 	if !strings.Contains(p.Message, "ou_missing_speaker") {
 		t.Errorf("message should include missing speaker id, got: %s", p.Message)
 	}
-	if !strings.Contains(p.Hint, "--from-user-id") {
-		t.Errorf("hint should mention --from-user-id, got: %s", p.Hint)
+	if !strings.Contains(p.Hint, "--from-speaker-id") {
+		t.Errorf("hint should mention --from-speaker-id, got: %s", p.Hint)
 	}
 }
 

shortcuts/minutes/minutes_speakers.go

@@ -0,0 +1,104 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type minuteSpeaker struct {
+	SpeakerID string
+	Name      string
+}
+
+func minuteTranscriptSpeakerlistPath(minuteToken string) string {
+	return fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speakerlist", validate.EncodePathSegment(minuteToken))
+}
+
+func fetchMinuteSpeakers(runtime *common.RuntimeContext, minuteToken string) ([]minuteSpeaker, error) {
+	data, err := runtime.CallAPITyped(http.MethodGet, minuteTranscriptSpeakerlistPath(minuteToken), nil, nil)
+	if err != nil {
+		return nil, err
+	}
+	if data == nil {
+		return nil, nil
+	}
+
+	items := common.GetSlice(data, "speakers")
+	speakers := make([]minuteSpeaker, 0, len(items))
+	for _, raw := range items {
+		item, _ := raw.(map[string]interface{})
+		if item == nil {
+			continue
+		}
+		id := strings.TrimSpace(common.GetString(item, "speaker_id"))
+		name := strings.TrimSpace(common.GetString(item, "name"))
+		if id == "" {
+			continue
+		}
+		speakers = append(speakers, minuteSpeaker{SpeakerID: id, Name: name})
+	}
+	return speakers, nil
+}
+
+func resolveSpeakerIDByName(speakers []minuteSpeaker, name string) (string, error) {
+	name = strings.TrimSpace(name)
+	var matches []minuteSpeaker
+	for _, s := range speakers {
+		if s.Name == name {
+			matches = append(matches, s)
+		}
+	}
+	switch len(matches) {
+	case 0:
+		return "", errs.NewValidationError(errs.SubtypeNotFound,
+			"no speaker named %q in minute transcript", name).
+			WithParam("--from-speaker-id").
+			WithHint("Check the speaker name spelling or open the minute to see transcript speaker labels")
+	case 1:
+		return matches[0].SpeakerID, nil
+	default:
+		ids := make([]string, len(matches))
+		for i, m := range matches {
+			ids[i] = m.SpeakerID
+		}
+		return "", errs.NewValidationError(errs.SubtypeFailedPrecondition,
+			"multiple speakers named %q (%d matches); pass the exact --from-speaker-id", name, len(matches)).
+			WithParam("--from-speaker-id").
+			WithHint(fmt.Sprintf("Matching speaker_ids: %s. Review each speaker's utterances in the minute, then retry with the exact speaker_id", strings.Join(ids, ", ")))
+	}
+}
+
+// resolveFromSpeakerID resolves --from-speaker-id to an API speaker_id.
+// The input may already be an opaque speaker_id, or a display name that requires
+// an internal speaker-list fetch.
+func resolveFromSpeakerID(runtime *common.RuntimeContext, minuteToken, input string) (string, error) {
+	input = strings.TrimSpace(input)
+	speakers, err := fetchMinuteSpeakers(runtime, minuteToken)
+	if err != nil {
+		return "", err
+	}
+	for _, s := range speakers {
+		if s.SpeakerID == input {
+			return input, nil
+		}
+	}
+	return resolveSpeakerIDByName(speakers, input)
+}
+
+func resolveSpeakerReplaceFrom(runtime *common.RuntimeContext, minuteToken string) (fromSpeakerID, fromUserID string, err error) {
+	fromUserID = strings.TrimSpace(runtime.Str("from-user-id"))
+	if fromUserID != "" {
+		return "", fromUserID, nil
+	}
+
+	fromSpeakerID, err = resolveFromSpeakerID(runtime, minuteToken, runtime.Str("from-speaker-id"))
+	return fromSpeakerID, "", err
+}

shortcuts/minutes/minutes_speakers_test.go

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+func TestResolveSpeakerIDByName(t *testing.T) {
+	speakers := []minuteSpeaker{
+		{SpeakerID: "id_a", Name: "Alice"},
+		{SpeakerID: "id_b", Name: "Bob"},
+		{SpeakerID: "id_c", Name: "Alice"},
+	}
+
+	id, err := resolveSpeakerIDByName(speakers, "Bob")
+	if err != nil || id != "id_b" {
+		t.Fatalf("resolve Bob: id=%q err=%v", id, err)
+	}
+
+	_, err = resolveSpeakerIDByName(speakers, "Carol")
+	if err == nil {
+		t.Fatal("expected not found error")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) || ve.Subtype != errs.SubtypeNotFound {
+		t.Fatalf("want not-found validation error, got %T: %v", err, err)
+	}
+
+	_, err = resolveSpeakerIDByName(speakers, "Alice")
+	if err == nil {
+		t.Fatal("expected duplicate name error")
+	}
+	if !errors.As(err, &ve) || ve.Subtype != errs.SubtypeFailedPrecondition {
+		t.Fatalf("want failed-precondition validation error, got %T: %v", err, err)
+	}
+	if !strings.Contains(ve.Hint, "id_a") || !strings.Contains(ve.Hint, "id_c") {
+		t.Errorf("hint should list matching speaker_ids, got: %s", ve.Hint)
+	}
+}

shortcuts/minutes/minutes_summary.go

@@ -31,7 +31,7 @@ var MinutesSummary = common.Shortcut{
 	},
 	Tips: []string{
 		minutesSummaryMarkdownTip,
-		"Use `lark-cli vc +notes --minute-tokens <token>` to read the current summary before replacing it.",
+		"Use `lark-cli minutes +detail --minute-tokens <token> --summary` to read the current summary before replacing it.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		minuteToken := runtime.Str("minute-token")

shortcuts/minutes/minutes_todo.go

@@ -59,7 +59,7 @@ var MinutesTodo = common.Shortcut{
 		"Update: `--operation update --todo-id <id> --todo \"...\" --is-done`.",
 		"Delete: `--operation delete --todo-id <id>`.",
 		"`content` is plain text only; markdown formatting is not supported.",
-		"Use `lark-cli vc +notes --minute-tokens <token>` to read current todos before writing.",
+		"Use `lark-cli minutes +detail --minute-tokens <token> --todo` to read current todos before writing.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		minuteToken := runtime.Str("minute-token")

shortcuts/minutes/minutes_word_replace.go

@@ -148,7 +148,7 @@ func minutesWordReplaceError(err error, minuteToken string) error {
 		if strings.Contains(strings.ToLower(p.Message), "not found in transcript") {
 			p.Subtype = errs.SubtypeNotFound
 			p.Message = fmt.Sprintf("None of the source words were found in minute %q transcript; nothing was replaced.", minuteToken)
-			p.Hint = "Verify each source_word's exact spelling and case against the current transcript (use vc +notes to read it), then retry"
+			p.Hint = "Verify each source_word's exact spelling and case against the current transcript (use `minutes +detail --minute-tokens <token> --transcript` to read it), then retry"
 		}
 	}
 

shortcuts/minutes/shortcuts.go

@@ -16,5 +16,6 @@ func Shortcuts() []common.Shortcut {
 		MinutesTodo,
 		MinutesSpeakerReplace,
 		MinutesWordReplace,
+		MinutesDetail,
 	}
 }

shortcuts/note/note_transcript.go

@@ -153,7 +153,7 @@ func ensureUnifiedNote(ctx context.Context, runtime *common.RuntimeContext, note
 	if detail.DisplayType != "unified" {
 		if detail.VerbatimDocToken != "" {
 			return errs.NewValidationError(errs.SubtypeFailedPrecondition, "note %s is not a unified note (note_display_type=%s, verbatim_doc_token=%s)", noteID, detail.DisplayType, detail.VerbatimDocToken).
-				WithHint("Use docs +fetch --api-version v2 --doc %s for normal note transcripts", detail.VerbatimDocToken)
+				WithHint("Use docs +fetch --doc %s for normal note transcripts", detail.VerbatimDocToken)
 		}
 		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "note %s is not a unified note (note_display_type=%s, verbatim_doc_token=)", noteID, detail.DisplayType).
 			WithHint("Use note +detail to inspect document tokens")

shortcuts/note/note_transcript_test.go

@@ -39,7 +39,7 @@ func TestNoteTranscriptRequiresUnifiedNote(t *testing.T) {
 	if problem.Subtype != errs.SubtypeFailedPrecondition {
 		t.Fatalf("subtype = %v, want FailedPrecondition", problem.Subtype)
 	}
-	if !strings.Contains(problem.Hint, "docs +fetch --api-version v2 --doc doc_verbatim") {
+	if !strings.Contains(problem.Hint, "docs +fetch --doc doc_verbatim") {
 		t.Fatalf("hint = %q, want docs +fetch guidance", problem.Hint)
 	}
 	if stdout.Len() != 0 {

shortcuts/register_test.go

@@ -246,7 +246,7 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
 			shortcutHelp: "Create a Lark document",
 			visibleFlag:  "--content",
 			skillCommand: "lark-cli skills read lark-doc references/lark-doc-create.md",
-			hiddenFlags:  []string{"markdown", "folder-token", "wiki-node", "wiki-space"},
+			hiddenFlags:  []string{"api-version", "markdown", "folder-token", "wiki-node", "wiki-space"},
 			contentHelp: []string{
 				"--title",
 				"AI agents MUST read",
@@ -258,7 +258,7 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
 				"MUST NOT grep/open local SKILL.md files",
 				"use --help for the latest command flags",
 			},
-			unwanted: []string{"--markdown", "--folder-token", "--wiki-node", "--wiki-space"},
+			unwanted: []string{"--api-version", "--markdown", "--folder-token", "--wiki-node", "--wiki-space"},
 		},
 		{
 			name:         "fetch",
@@ -266,8 +266,8 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
 			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"},
+			hiddenFlags:  []string{"api-version", "offset", "limit"},
+			unwanted:     []string{"--api-version", "--offset", "--limit"},
 		},
 		{
 			name:         "update",
@@ -275,7 +275,7 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
 			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"},
+			hiddenFlags:  []string{"api-version", "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",
@@ -286,7 +286,7 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
 				"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"},
+			unwanted: []string{"--api-version", "--mode", "--markdown", "--selection-with-ellipsis", "--selection-by-title", "--new-title"},
 		},
 	}
 
@@ -312,17 +312,6 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
 					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)
-			}
-
 			var out bytes.Buffer
 			cmd.SetOut(&out)
 			if err := cmd.Help(); err != nil {
@@ -332,10 +321,6 @@ func TestRegisterShortcutsDocsShortcutHelpIsV2Only(t *testing.T) {
 			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",

shortcuts/sheets/backward/lark_sheets_float_images.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"fmt"
 	"path/filepath"
+	"strings"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
@@ -14,7 +15,25 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-const sheetImageParentType = "sheet_image"
+// Drive media parent_type values for uploading an image into a spreadsheet.
+// Native spreadsheets use "sheet_image"; imported "office" spreadsheets carry a
+// synthetic token prefixed with "fake_office_" and the backend requires
+// "office_sheet_file" instead.
+const (
+	sheetImageParentType      = "sheet_image"
+	officeSheetFileParentType = "office_sheet_file"
+	fakeOfficeTokenPrefix     = "fake_office_"
+)
+
+// sheetMediaParentType returns the drive media parent_type to use when
+// uploading an image whose parent_node is spreadsheetToken, mapping the
+// "fake_office_" imported-spreadsheet token prefix to "office_sheet_file".
+func sheetMediaParentType(spreadsheetToken string) string {
+	if strings.HasPrefix(spreadsheetToken, fakeOfficeTokenPrefix) {
+		return officeSheetFileParentType
+	}
+	return sheetImageParentType
+}
 
 var SheetMediaUpload = common.Shortcut{
 	Service:     "sheets",
@@ -49,7 +68,7 @@ var SheetMediaUpload = common.Shortcut{
 				POST("/open-apis/drive/v1/medias/upload_prepare").
 				Body(map[string]interface{}{
 					"file_name":   fileName,
-					"parent_type": sheetImageParentType,
+					"parent_type": sheetMediaParentType(parentNode),
 					"parent_node": parentNode,
 					"size":        "<file_size>",
 				}).
@@ -71,7 +90,7 @@ var SheetMediaUpload = common.Shortcut{
 			POST("/open-apis/drive/v1/medias/upload_all").
 			Body(map[string]interface{}{
 				"file_name":   fileName,
-				"parent_type": sheetImageParentType,
+				"parent_type": sheetMediaParentType(parentNode),
 				"parent_node": parentNode,
 				"size":        "<file_size>",
 				"file":        "@" + filePath,
@@ -141,13 +160,14 @@ func resolveSheetMediaUploadParent(runtime *common.RuntimeContext) (string, erro
 }
 
 func uploadSheetMediaFile(runtime *common.RuntimeContext, filePath, fileName string, fileSize int64, parentNode string) (string, error) {
+	parentType := sheetMediaParentType(parentNode)
 	if fileSize <= common.MaxDriveMediaUploadSinglePartSize {
 		pn := parentNode
 		return common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
 			FilePath:   filePath,
 			FileName:   fileName,
 			FileSize:   fileSize,
-			ParentType: sheetImageParentType,
+			ParentType: parentType,
 			ParentNode: &pn,
 		})
 	}
@@ -155,7 +175,7 @@ func uploadSheetMediaFile(runtime *common.RuntimeContext, filePath, fileName str
 		FilePath:   filePath,
 		FileName:   fileName,
 		FileSize:   fileSize,
-		ParentType: sheetImageParentType,
+		ParentType: parentType,
 		ParentNode: parentNode,
 	})
 }

shortcuts/sheets/backward/lark_sheets_sheet_media_upload_test.go

@@ -91,6 +91,39 @@ func TestSheetMediaUploadDryRunSmallFile(t *testing.T) {
 	}
 }
 
+// TestSheetMediaUploadDryRunSmallFileOfficeParentType pins the small-file
+// upload_all dry-run preview to the token-derived parent_type so the preview
+// agents/users will copy matches what Execute actually sends. Without this the
+// multipart dry-run branch could drift back to a hard-coded "sheet_image".
+func TestSheetMediaUploadDryRunSmallFileOfficeParentType(t *testing.T) {
+	dir := t.TempDir()
+	withSheetsTestWorkingDir(t, dir)
+	if err := os.WriteFile("img.png", []byte("png-bytes"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, sheetsTestConfig())
+	err := mountAndRunSheets(t, SheetMediaUpload, []string{
+		"+media-upload",
+		"--spreadsheet-token", "fake_office_abc123",
+		"--file", "img.png",
+		"--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "/open-apis/drive/v1/medias/upload_all") {
+		t.Fatalf("dry-run should use upload_all for small file, got: %s", out)
+	}
+	if !strings.Contains(out, `"office_sheet_file"`) {
+		t.Fatalf("dry-run should include parent_type=office_sheet_file for fake_office_ token, got: %s", out)
+	}
+	if strings.Contains(out, `"sheet_image"`) {
+		t.Fatalf("dry-run must not emit sheet_image for fake_office_ token, got: %s", out)
+	}
+}
+
 func TestSheetMediaUploadDryRunURLExtractsToken(t *testing.T) {
 	dir := t.TempDir()
 	withSheetsTestWorkingDir(t, dir)
@@ -205,6 +238,47 @@ func TestSheetMediaUploadExecuteSuccess(t *testing.T) {
 	}
 }
 
+// TestSheetMediaUploadExecuteOfficeParentType confirms that an imported
+// "office" spreadsheet (token prefixed with "fake_office_") uploads with
+// parent_type=office_sheet_file instead of the native sheet_image.
+func TestSheetMediaUploadExecuteOfficeParentType(t *testing.T) {
+	dir := t.TempDir()
+	withSheetsTestWorkingDir(t, dir)
+	if err := os.WriteFile("img.png", []byte("png-bytes"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, sheetsTestConfig())
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"file_token": "boxTOK123"},
+		},
+	}
+	reg.Register(stub)
+
+	const officeToken = "fake_office_abc123"
+	err := mountAndRunSheets(t, SheetMediaUpload, []string{
+		"+media-upload",
+		"--spreadsheet-token", officeToken,
+		"--file", "img.png",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	body := decodeSheetsMultipartBody(t, stub)
+	if got := body.Fields["parent_type"]; got != officeSheetFileParentType {
+		t.Fatalf("parent_type = %q, want %q", got, officeSheetFileParentType)
+	}
+	if got := body.Fields["parent_node"]; got != officeToken {
+		t.Fatalf("parent_node = %q, want %q", got, officeToken)
+	}
+}
+
 func TestSheetMediaUploadFileNotFound(t *testing.T) {
 	dir := t.TempDir()
 	withSheetsTestWorkingDir(t, dir)

shortcuts/sheets/batch_op_dispatch.go

@@ -332,11 +332,21 @@ func translateBatchOp(raw interface{}, token string, index int) (map[string]inte
 	}, nil
 }
 
+// maxBatchOperations caps how many sub-operations a single +batch-update may
+// carry. Every translated op (with its own cells/properties payload) is held in
+// the out slice at once before the whole batch is marshaled, so an unbounded
+// operation count is the same unbounded-materialization hazard as the fan-out
+// matrix, on the operations axis.
+const maxBatchOperations = 100
+
 // translateBatchOperations 翻译整个 ops 数组；fail-fast，遇错立即返回。
 func translateBatchOperations(rawOps []interface{}, token string) ([]interface{}, error) {
 	if len(rawOps) == 0 {
 		return nil, sheetsValidationForFlag("operations", "--operations must be a non-empty JSON array")
 	}
+	if len(rawOps) > maxBatchOperations {
+		return nil, sheetsValidationForFlag("operations", "--operations accepts at most %d entries; got %d", maxBatchOperations, len(rawOps))
+	}
 	out := make([]interface{}, 0, len(rawOps))
 	for i, raw := range rawOps {
 		translated, err := translateBatchOp(raw, token, i)

shortcuts/sheets/data/flag-defs.json

@@ -1,4 +1,59 @@
 {
+  "+formula-verify": {
+    "risk": "read",
+    "flags": [
+      {
+        "name": "url",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet URL (XOR with `--spreadsheet-token`)"
+      },
+      {
+        "name": "spreadsheet-token",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet token (XOR with `--url`)"
+      },
+      {
+        "name": "sheet-id",
+        "kind": "public",
+        "type": "string_slice",
+        "required": "optional",
+        "desc": "Sheet reference_id(s); repeat or comma-separate to scan multiple sheets. Omit to scan all visible sheets."
+      },
+      {
+        "name": "sheet-name",
+        "kind": "public",
+        "type": "string_slice",
+        "required": "optional",
+        "desc": "Sheet name(s); repeat or comma-separate to scan multiple sheets. Omit to scan all visible sheets."
+      },
+      {
+        "name": "range",
+        "kind": "own",
+        "type": "string_slice",
+        "required": "optional",
+        "desc": "Optional A1 ranges (e.g. `A1:Z200`); repeat or comma-separate for multiple ranges. Omit to scan each sheet's current_region."
+      },
+      {
+        "name": "max-locations",
+        "kind": "own",
+        "type": "int",
+        "required": "optional",
+        "desc": "Max locations / samples per error type; default 20.",
+        "default": "20"
+      },
+      {
+        "name": "exit-on-error",
+        "kind": "own",
+        "type": "bool",
+        "required": "optional",
+        "desc": "When status=errors_found, exit non-zero. Useful for CI gate after batch formula writes."
+      }
+    ]
+  },
   "+workbook-info": {
     "risk": "read",
     "flags": [
@@ -73,6 +128,14 @@
         "desc": "Initial column count (default 20, max 200)",
         "default": "20"
       },
+      {
+        "name": "type",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "New sub-sheet type: sheet (spreadsheet) | bitable; default sheet. bitable creates an empty table only — edit its content via lark-base commands",
+        "default": "sheet"
+      },
       {
         "name": "dry-run",
         "kind": "system",
@@ -219,7 +282,7 @@
         "kind": "own",
         "type": "int",
         "required": "optional",
-        "desc": "Source position (0-based); optional. If omitted, the CLI runtime derives it from the current workbook index of `--sheet-id` / `--sheet-name`",
+        "desc": "Source position (0-based); optional for standalone calls — if omitted, the CLI runtime derives it from the current workbook index of `--sheet-id` / `--sheet-name`. Inside `+batch-update` it must be passed explicitly, since batch cannot issue a structure query mid-run to derive it",
         "default": "-1"
       },
       {
@@ -515,7 +578,7 @@
         "kind": "own",
         "type": "string",
         "required": "optional",
-        "desc": "Untyped initial data as one 2D JSON array (`[[\"alice\",95]]`); values are written as-is with their type auto-detected, through the same batched set_cell_range path as --sheets — pair with --styles for number formats, colors, merges, and row/col sizes",
+        "desc": "Untyped initial data as one 2D JSON array (`[[\"alice\",95]]`); values are written as-is with their type auto-detected (dates / numbers land as text — use --sheets to preserve types), through the same batched set_cell_range path as --sheets — pair with --styles for number formats, colors, merges, and row/col sizes",
         "input": [
           "file",
           "stdin"
@@ -1069,7 +1132,7 @@
         "kind": "own",
         "type": "int",
         "required": "optional",
-        "desc": "Group nesting level to ungroup; default 1 (outermost)",
+        "desc": "Group nesting level to ungroup; default 1 (1 = outermost, larger = deeper)",
         "default": "1"
       },
       {
@@ -1711,6 +1774,13 @@
         "required": "optional",
         "desc": "Font color (hex, e.g. `#000000`)"
       },
+      {
+        "name": "font-family",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "Font family name (e.g. `Arial`, `Microsoft YaHei`)"
+      },
       {
         "name": "font-size",
         "kind": "own",
@@ -2739,7 +2809,7 @@
         "kind": "own",
         "type": "string",
         "required": "required",
-        "desc": "Target ranges as a JSON array (e.g. `[\"'Sheet1'!A1:B2\",\"'Sheet2'!D1:D10\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id; ranges may target different sheets; the same style is applied to every range",
+        "desc": "Target ranges as a JSON array (e.g. `[\"Sheet1!A1:B2\",\"Sheet2!D1:D10\"]`, prefix written bare without quotes); each prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id; ranges may target different sheets; the same style is applied to every range",
         "input": [
           "file",
           "stdin"
@@ -2759,6 +2829,13 @@
         "required": "optional",
         "desc": "Font color (hex, e.g. `#000000`)"
       },
+      {
+        "name": "font-family",
+        "kind": "own",
+        "type": "string",
+        "required": "optional",
+        "desc": "Font family name (e.g. `Arial`, `Microsoft YaHei`)"
+      },
       {
         "name": "font-size",
         "kind": "own",
@@ -2885,7 +2962,7 @@
         "kind": "own",
         "type": "string",
         "required": "required",
-        "desc": "Target ranges as a JSON array (e.g. `[\"'Sheet1'!A2:A100\",\"'Sheet1'!C2:C100\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id",
+        "desc": "Target ranges as a JSON array (e.g. `[\"Sheet1!A2:A100\",\"Sheet1!C2:C100\"]`, prefix written bare without quotes); each item must include a sheet prefix; the prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id",
         "input": [
           "file",
           "stdin"
@@ -2965,7 +3042,7 @@
         "kind": "own",
         "type": "string",
         "required": "required",
-        "desc": "Target ranges as a JSON array (up to 100 items, e.g. `[\"'Sheet1'!E2:E6\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id",
+        "desc": "Target ranges as a JSON array (up to 100 items, e.g. `[\"Sheet1!E2:E6\"]`, prefix written bare without quotes); each item must include a sheet prefix; the prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id",
         "input": [
           "file",
           "stdin"
@@ -3009,7 +3086,7 @@
         "kind": "own",
         "type": "string",
         "required": "required",
-        "desc": "Target ranges as a JSON array (e.g. `[\"'Sheet1'!A2:Z1000\",\"'Sheet2'!A2:Z1000\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id; ranges may target different sheets; the same scope is cleared from every range",
+        "desc": "Target ranges as a JSON array (e.g. `[\"Sheet1!A2:Z1000\",\"Sheet2!A2:Z1000\"]`, prefix written bare without quotes); each prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id; ranges may target different sheets; the same scope is cleared from every range",
         "input": [
           "file",
           "stdin"
@@ -3127,7 +3204,7 @@
         "kind": "own",
         "type": "string",
         "required": "required",
-        "desc": "Full chart config JSON. Top-level keys: `position` / `offset` / `size` / `snapshot` (no top-level `data`, no extra nested `properties`); chart data config lives under `snapshot.data` (`refs` / `headerMode` / `dim1` / `dim2`). Deeply nested — run `--print-schema --flag-name properties` for the full structure.",
+        "desc": "Full chart config JSON. Top-level keys: `position` / `offset` / `size` / `snapshot` (no top-level `data`, no extra nested `properties`); chart data config lives under `snapshot.data` (`refs` / `headerMode` / `dim1` / `dim2`); must include at least one of `snapshot.data.dim1.serie.index` or `dim2.series[].index`, otherwise the server rejects it. Deeply nested — run `--print-schema --flag-name properties` for the full structure.",
         "input": [
           "file",
           "stdin"
@@ -4066,7 +4143,7 @@
         "kind": "own",
         "type": "string",
         "required": "optional",
-        "desc": "Filter-view name; auto-assigned by the server when omitted on create, kept unchanged when omitted on update; takes precedence over the same-named field inside `--properties`"
+        "desc": "Filter-view name; auto-assigned by the server when omitted; takes precedence over the same-named field inside `--properties`"
       },
       {
         "name": "dry-run",
@@ -4747,5 +4824,104 @@
         "desc": ""
       }
     ]
+  },
+  "+history-list": {
+    "risk": "read",
+    "flags": [
+      {
+        "name": "url",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "spreadsheet-token",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "end-version",
+        "kind": "own",
+        "type": "int",
+        "required": "optional",
+        "desc": "Max version to query (descending pagination). Omit on the first call; pass next_end_version from the previous response."
+      },
+      {
+        "name": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": ""
+      }
+    ]
+  },
+  "+history-revert": {
+    "risk": "write",
+    "flags": [
+      {
+        "name": "url",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "spreadsheet-token",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "history-version-id",
+        "kind": "own",
+        "type": "string",
+        "required": "required",
+        "desc": "History version to revert to (from +history-list)."
+      },
+      {
+        "name": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": ""
+      }
+    ]
+  },
+  "+history-revert-status": {
+    "risk": "read",
+    "flags": [
+      {
+        "name": "url",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "spreadsheet-token",
+        "kind": "public",
+        "type": "string",
+        "required": "xor",
+        "desc": "Spreadsheet locator"
+      },
+      {
+        "name": "transaction-id",
+        "kind": "own",
+        "type": "string",
+        "required": "required",
+        "desc": "Async revert transaction id (from +history-revert)."
+      },
+      {
+        "name": "dry-run",
+        "kind": "system",
+        "type": "bool",
+        "required": "optional",
+        "desc": ""
+      }
+    ]
   }
 }

shortcuts/sheets/flag_defs_gen.go

@@ -27,7 +27,7 @@ var flagDefs = map[string]commandDef{
 		Flags: []flagDef{
 			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet URL (XOR with `--spreadsheet-token`)"},
 			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
-			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (e.g. `[\"'Sheet1'!A2:Z1000\",\"'Sheet2'!A2:Z1000\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id; ranges may target different sheets; the same scope is cleared from every range", Input: []string{"file", "stdin"}},
+			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (e.g. `[\"Sheet1!A2:Z1000\",\"Sheet2!A2:Z1000\"]`, prefix written bare without quotes); each prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id; ranges may target different sheets; the same scope is cleared from every range", Input: []string{"file", "stdin"}},
 			{Name: "scope", Kind: "own", Type: "string", Required: "optional", Desc: "Clear scope: `content` (default, values only) / `formats` (formats only) / `all` (values and formats)", Default: "content", Enum: []string{"content", "formats", "all"}},
 			{Name: "yes", Kind: "system", Type: "bool", Required: "required", Desc: "Confirm destructive write (exit code 10 without this flag); batch clear is irreversible"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
@@ -38,9 +38,10 @@ var flagDefs = map[string]commandDef{
 		Flags: []flagDef{
 			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet URL (XOR with `--spreadsheet-token`)"},
 			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
-			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (e.g. `[\"'Sheet1'!A1:B2\",\"'Sheet2'!D1:D10\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id; ranges may target different sheets; the same style is applied to every range", Input: []string{"file", "stdin"}},
+			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (e.g. `[\"Sheet1!A1:B2\",\"Sheet2!D1:D10\"]`, prefix written bare without quotes); each prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id; ranges may target different sheets; the same style is applied to every range", Input: []string{"file", "stdin"}},
 			{Name: "background-color", Kind: "own", Type: "string", Required: "optional", Desc: "Background color (hex, e.g. `#ffffff`)"},
 			{Name: "font-color", Kind: "own", Type: "string", Required: "optional", Desc: "Font color (hex, e.g. `#000000`)"},
+			{Name: "font-family", Kind: "own", Type: "string", Required: "optional", Desc: "Font family name (e.g. `Arial`, `Microsoft YaHei`)"},
 			{Name: "font-size", Kind: "own", Type: "float64", Required: "optional", Desc: "Font size in px (e.g. 10, 12, 14)"},
 			{Name: "font-style", Kind: "own", Type: "string", Required: "optional", Desc: "Font style", Enum: []string{"normal", "italic"}},
 			{Name: "font-weight", Kind: "own", Type: "string", Required: "optional", Desc: "Font weight", Enum: []string{"normal", "bold"}},
@@ -165,6 +166,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "range", Kind: "own", Type: "string", Required: "required", Desc: "Target range (A1 notation, e.g. `A1:B2`)"},
 			{Name: "background-color", Kind: "own", Type: "string", Required: "optional", Desc: "Background color (hex, e.g. `#ffffff`)"},
 			{Name: "font-color", Kind: "own", Type: "string", Required: "optional", Desc: "Font color (hex, e.g. `#000000`)"},
+			{Name: "font-family", Kind: "own", Type: "string", Required: "optional", Desc: "Font family name (e.g. `Arial`, `Microsoft YaHei`)"},
 			{Name: "font-size", Kind: "own", Type: "float64", Required: "optional", Desc: "Font size in px (e.g. 10, 12, 14)"},
 			{Name: "font-style", Kind: "own", Type: "string", Required: "optional", Desc: "Font style", Enum: []string{"normal", "italic"}},
 			{Name: "font-weight", Kind: "own", Type: "string", Required: "optional", Desc: "Font weight", Enum: []string{"normal", "bold"}},
@@ -195,7 +197,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
 			{Name: "sheet-id", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet reference_id (XOR with `--sheet-name`)"},
 			{Name: "sheet-name", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet name (XOR with `--sheet-id`)"},
-			{Name: "properties", Kind: "own", Type: "string", Required: "required", Desc: "Full chart config JSON. Top-level keys: `position` / `offset` / `size` / `snapshot` (no top-level `data`, no extra nested `properties`); chart data config lives under `snapshot.data` (`refs` / `headerMode` / `dim1` / `dim2`). Deeply nested — run `--print-schema --flag-name properties` for the full structure.", Input: []string{"file", "stdin"}},
+			{Name: "properties", Kind: "own", Type: "string", Required: "required", Desc: "Full chart config JSON. Top-level keys: `position` / `offset` / `size` / `snapshot` (no top-level `data`, no extra nested `properties`); chart data config lives under `snapshot.data` (`refs` / `headerMode` / `dim1` / `dim2`); must include at least one of `snapshot.data.dim1.serie.index` or `dim2.series[].index`, otherwise the server rejects it. Deeply nested — run `--print-schema --flag-name properties` for the full structure.", Input: []string{"file", "stdin"}},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional", Desc: "Print the request template; no side effects"},
 		},
 	},
@@ -405,7 +407,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
 			{Name: "sheet-id", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet reference_id (XOR with `--sheet-name`)"},
 			{Name: "sheet-name", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet name (XOR with `--sheet-id`)"},
-			{Name: "depth", Kind: "own", Type: "int", Required: "optional", Desc: "Group nesting level to ungroup; default 1 (outermost)", Default: "1"},
+			{Name: "depth", Kind: "own", Type: "int", Required: "optional", Desc: "Group nesting level to ungroup; default 1 (1 = outermost, larger = deeper)", Default: "1"},
 			{Name: "range", Kind: "own", Type: "string", Required: "required", Desc: "Row/column closed range to ungroup; rows use 1-based numbers like `3:7`, columns use letters like `C:F`"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
@@ -426,7 +428,7 @@ var flagDefs = map[string]commandDef{
 		Flags: []flagDef{
 			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet URL (XOR with `--spreadsheet-token`)"},
 			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
-			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (up to 100 items, e.g. `[\"'Sheet1'!E2:E6\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id", Input: []string{"file", "stdin"}},
+			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (up to 100 items, e.g. `[\"Sheet1!E2:E6\"]`, prefix written bare without quotes); each item must include a sheet prefix; the prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id", Input: []string{"file", "stdin"}},
 			{Name: "yes", Kind: "system", Type: "bool", Required: "required", Desc: "Confirm high-risk write (exit code 10 without this flag)"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
@@ -463,7 +465,7 @@ var flagDefs = map[string]commandDef{
 		Flags: []flagDef{
 			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet URL (XOR with `--spreadsheet-token`)"},
 			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
-			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (e.g. `[\"'Sheet1'!A2:A100\",\"'Sheet1'!C2:C100\"]`); each item must include a sheet prefix; the prefix must be the sheet display name (e.g. `Sheet1`), not the sheet reference_id", Input: []string{"file", "stdin"}},
+			{Name: "ranges", Kind: "own", Type: "string", Required: "required", Desc: "Target ranges as a JSON array (e.g. `[\"Sheet1!A2:A100\",\"Sheet1!C2:C100\"]`, prefix written bare without quotes); each item must include a sheet prefix; the prefix must exactly match the sheet display name (case-sensitive), not the sheet reference_id", Input: []string{"file", "stdin"}},
 			{Name: "options", Kind: "own", Type: "string", Required: "xor", Desc: "Options as a JSON array, e.g. `[\"opt1\",\"opt2\"]`. Server enforces no item-count cap and no per-item length cap; values containing commas are accepted (they are escape-encoded on the wire). For very large lists prefer `--source-range`.", Input: []string{"file", "stdin"}},
 			{Name: "colors", Kind: "own", Type: "string", Required: "optional", Desc: "Per-option pill colors, RGB hex array (e.g. `[\"#1FB6C1\",\"#F006C2\"]`). Length may be shorter than the source (`--options` items / `--source-range` cells) — extras cycle through a 10-color palette — but never longer (CLI Validate rejects: `--colors length (N) must not exceed dropdown source size (M)`). **Applies on its own**; ignored when `--highlight=false`.", Input: []string{"file", "stdin"}},
 			{Name: "multiple", Kind: "own", Type: "bool", Required: "optional", Desc: "Enable multi-select"},
@@ -526,7 +528,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "sheet-name", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet name (XOR with `--sheet-id`)"},
 			{Name: "properties", Kind: "own", Type: "string", Required: "required", Desc: "Filter-view rule JSON: `rules?` (per-column rule array), `filtered_columns?`. `range` and `view_name` are separate flags", Input: []string{"file", "stdin"}},
 			{Name: "range", Kind: "own", Type: "string", Required: "required", Desc: "Range the filter view applies to (A1 notation, e.g. `A1:F1000`); takes precedence over the same-named field inside `--properties`; required on create and must cover the header row"},
-			{Name: "view-name", Kind: "own", Type: "string", Required: "optional", Desc: "Filter-view name; auto-assigned by the server when omitted on create, kept unchanged when omitted on update; takes precedence over the same-named field inside `--properties`"},
+			{Name: "view-name", Kind: "own", Type: "string", Required: "optional", Desc: "Filter-view name; auto-assigned by the server when omitted; takes precedence over the same-named field inside `--properties`"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
@@ -632,6 +634,45 @@ var flagDefs = map[string]commandDef{
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
+	"+formula-verify": {
+		Risk: "read",
+		Flags: []flagDef{
+			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet URL (XOR with `--spreadsheet-token`)"},
+			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet token (XOR with `--url`)"},
+			{Name: "sheet-id", Kind: "public", Type: "string_slice", Required: "optional", Desc: "Sheet reference_id(s); repeat or comma-separate to scan multiple sheets. Omit to scan all visible sheets."},
+			{Name: "sheet-name", Kind: "public", Type: "string_slice", Required: "optional", Desc: "Sheet name(s); repeat or comma-separate to scan multiple sheets. Omit to scan all visible sheets."},
+			{Name: "range", Kind: "own", Type: "string_slice", Required: "optional", Desc: "Optional A1 ranges (e.g. `A1:Z200`); repeat or comma-separate for multiple ranges. Omit to scan each sheet's current_region."},
+			{Name: "max-locations", Kind: "own", Type: "int", Required: "optional", Desc: "Max locations / samples per error type; default 20.", Default: "20"},
+			{Name: "exit-on-error", Kind: "own", Type: "bool", Required: "optional", Desc: "When status=errors_found, exit non-zero. Useful for CI gate after batch formula writes."},
+		},
+	},
+	"+history-list": {
+		Risk: "read",
+		Flags: []flagDef{
+			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "end-version", Kind: "own", Type: "int", Required: "optional", Desc: "Max version to query (descending pagination). Omit on the first call; pass next_end_version from the previous response."},
+			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
+	"+history-revert": {
+		Risk: "write",
+		Flags: []flagDef{
+			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "history-version-id", Kind: "own", Type: "string", Required: "required", Desc: "History version to revert to (from +history-list)."},
+			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
+	"+history-revert-status": {
+		Risk: "read",
+		Flags: []flagDef{
+			{Name: "url", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "spreadsheet-token", Kind: "public", Type: "string", Required: "xor", Desc: "Spreadsheet locator"},
+			{Name: "transaction-id", Kind: "own", Type: "string", Required: "required", Desc: "Async revert transaction id (from +history-revert)."},
+			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
+		},
+	},
 	"+pivot-create": {
 		Risk: "write",
 		Flags: []flagDef{
@@ -768,6 +809,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "index", Kind: "own", Type: "int", Required: "optional", Desc: "Insert position (0-based); appended to the end when omitted", Default: "-1"},
 			{Name: "row-count", Kind: "own", Type: "int", Required: "optional", Desc: "Initial row count (default 200, max 50000)", Default: "200"},
 			{Name: "col-count", Kind: "own", Type: "int", Required: "optional", Desc: "Initial column count (default 20, max 200)", Default: "20"},
+			{Name: "type", Kind: "own", Type: "string", Required: "optional", Desc: "New sub-sheet type: sheet (spreadsheet) | bitable; default sheet. bitable creates an empty table only — edit its content via lark-base commands", Default: "sheet"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
@@ -822,7 +864,7 @@ var flagDefs = map[string]commandDef{
 			{Name: "sheet-id", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet reference_id (XOR with `--sheet-name`)"},
 			{Name: "sheet-name", Kind: "public", Type: "string", Required: "xor", Desc: "Sheet name (XOR with `--sheet-id`)"},
 			{Name: "index", Kind: "own", Type: "int", Required: "required", Desc: "Target position (0-based)"},
-			{Name: "source-index", Kind: "own", Type: "int", Required: "optional", Desc: "Source position (0-based); optional. If omitted, the CLI runtime derives it from the current workbook index of `--sheet-id` / `--sheet-name`", Default: "-1"},
+			{Name: "source-index", Kind: "own", Type: "int", Required: "optional", Desc: "Source position (0-based); optional for standalone calls — if omitted, the CLI runtime derives it from the current workbook index of `--sheet-id` / `--sheet-name`. Inside `+batch-update` it must be passed explicitly, since batch cannot issue a structure query mid-run to derive it", Default: "-1"},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},
 		},
 	},
@@ -941,7 +983,7 @@ var flagDefs = map[string]commandDef{
 		Flags: []flagDef{
 			{Name: "title", Kind: "own", Type: "string", Required: "required", Desc: "Spreadsheet title"},
 			{Name: "folder-token", Kind: "own", Type: "string", Required: "optional", Desc: "Target folder token; placed at the drive root when omitted"},
-			{Name: "values", Kind: "own", Type: "string", Required: "optional", Desc: "Untyped initial data as one 2D JSON array (`[[\"alice\",95]]`); values are written as-is with their type auto-detected, through the same batched set_cell_range path as --sheets — pair with --styles for number formats, colors, merges, and row/col sizes", Input: []string{"file", "stdin"}},
+			{Name: "values", Kind: "own", Type: "string", Required: "optional", Desc: "Untyped initial data as one 2D JSON array (`[[\"alice\",95]]`); values are written as-is with their type auto-detected (dates / numbers land as text — use --sheets to preserve types), through the same batched set_cell_range path as --sheets — pair with --styles for number formats, colors, merges, and row/col sizes", Input: []string{"file", "stdin"}},
 			{Name: "sheets", Kind: "own", Type: "string", Required: "optional", Desc: "Typed table payload as JSON (same shape as `+table-put`): top-level `{\"sheets\":[...]}`, with each array item a sub-sheet `{name, start_cell?, mode?, header?, allow_overwrite?, columns:[\"colA\",\"colB\",...], data:[[...]], dtypes?:{colA:pandasDtype, ...}, formats?:{colA:numberFormat, ...}}` — `name` and the outer `sheets` envelope are both required. Agents typically use `df_to_sheet(df, name)` from `scripts/sheets_df.py` to pack each DataFrame into one item, then wrap the list in `{\"sheets\":[...]}`. Mutually exclusive with --values. Creates the workbook, then writes typed type-faithful data (dates land as real dates, numbers keep precision).", Input: []string{"file", "stdin"}},
 			{Name: "styles", Kind: "own", Type: "string", Required: "optional", Desc: "Initial visual operations as JSON: top-level `{styles:[...]}`. Each item corresponds to one target sheet and must include `name`, plus at least one of `cell_styles` / `row_sizes` / `col_sizes` / `cell_merges`. `cell_styles` entries use +cells-set-style fields with a cell range; row/col sizes use dimension ranges plus type/size; merges use cell ranges plus optional merge_type. With --sheets, styles array length/order/name must match --sheets.sheets. With --values, pass exactly one styles item for the initial sheet (its name is ignored).", Input: []string{"file", "stdin"}},
 			{Name: "dry-run", Kind: "system", Type: "bool", Required: "optional"},

shortcuts/sheets/helpers.go

@@ -50,6 +50,42 @@ func sheetsInputStatError(flag string, err error) error {
 	return wrapped
 }
 
+// Drive media parent_type values for uploading an image into a spreadsheet.
+// Native spreadsheets use "sheet_image"; imported "office" spreadsheets carry a
+// synthetic token prefixed with "fake_office_" and the backend requires
+// "office_sheet_file" instead.
+const (
+	sheetImageParentType      = "sheet_image"
+	officeSheetFileParentType = "office_sheet_file"
+	fakeOfficeTokenPrefix     = "fake_office_"
+)
+
+// sheetMediaParentType returns the drive media parent_type to use when
+// uploading an image whose parent_node is spreadsheetToken. It is the single
+// place that maps a spreadsheet token to its parent_type so every image-upload
+// entry point (and its dry-run preview) stays consistent.
+func sheetMediaParentType(spreadsheetToken string) string {
+	if strings.HasPrefix(spreadsheetToken, fakeOfficeTokenPrefix) {
+		return officeSheetFileParentType
+	}
+	return sheetImageParentType
+}
+
+// uploadSheetImage uploads a local image file as a spreadsheet media asset and
+// returns its file_token. It funnels every sheets image upload through one
+// place so the parent_type selection (see sheetMediaParentType) is never
+// duplicated or forgotten at a call site. Callers are expected to have already
+// resolved spreadsheetToken (the upload's parent_node) and stat'd the file.
+func uploadSheetImage(runtime *common.RuntimeContext, spreadsheetToken, filePath, fileName string, fileSize int64) (string, error) {
+	return common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
+		FilePath:   filePath,
+		FileName:   fileName,
+		FileSize:   fileSize,
+		ParentType: sheetMediaParentType(spreadsheetToken),
+		ParentNode: &spreadsheetToken,
+	})
+}
+
 // spreadsheetRef classification: a --url / --spreadsheet-token input names a
 // spreadsheet either directly (a /sheets/ URL or raw token) or indirectly via a
 // wiki node that must be resolved to its backing spreadsheet at Execute time.
@@ -404,7 +440,7 @@ func requireJSONArray(runtime flagView, name string) ([]interface{}, error) {
 
 // ─── style flags (shared by +cells-set-style and +cells-batch-set-style) ─
 
-// buildCellStyleFromFlags reads the 11 flat style flags and returns the
+// buildCellStyleFromFlags reads the 12 flat style flags and returns the
 // cell_styles map expected by set_cell_range. Skips any flag the user
 // didn't set so partial styles work.
 func buildCellStyleFromFlags(runtime flagView) map[string]interface{} {
@@ -415,6 +451,9 @@ func buildCellStyleFromFlags(runtime flagView) map[string]interface{} {
 	if v := runtime.Str("font-color"); v != "" {
 		style["font_color"] = v
 	}
+	if v := runtime.Str("font-family"); v != "" {
+		style["font_family"] = v
+	}
 	if runtime.Changed("font-size") && runtime.Float64("font-size") > 0 {
 		style["font_size"] = runtime.Float64("font-size")
 	}

shortcuts/sheets/lark_sheet_batch_update.go

@@ -215,7 +215,8 @@ func cellsBatchSetStyleInput(runtime *common.RuntimeContext, token string) (map[
 	if borderStyles != nil {
 		prototype["border_styles"] = borderStyles
 	}
-	var ops []interface{}
+	ops := make([]interface{}, 0, len(ranges))
+	var totalCells int64
 	for _, rng := range ranges {
 		sheet, sub, err := splitSheetPrefixedRange(rng)
 		if err != nil {
@@ -225,6 +226,13 @@ func cellsBatchSetStyleInput(runtime *common.RuntimeContext, token string) (map[
 		if err != nil {
 			return nil, sheetsValidationForFlag("range", "range %q: %v", rng, err)
 		}
+		if err := checkStampMatrixBudget("ranges", rng, rows, cols); err != nil {
+			return nil, err
+		}
+		totalCells += int64(rows) * int64(cols)
+		if err := checkBatchStampBudget(totalCells); err != nil {
+			return nil, err
+		}
 		cells := fillCellsMatrix(rows, cols, prototype)
 		ops = append(ops, map[string]interface{}{
 			"tool_name": "set_cell_range",
@@ -299,7 +307,7 @@ func cellsBatchClearInput(runtime *common.RuntimeContext, token string) (map[str
 		return nil, err
 	}
 	clearType := normalizeClearType(runtime.Str("scope"))
-	var ops []interface{}
+	ops := make([]interface{}, 0, len(ranges))
 	for _, rng := range ranges {
 		sheet, sub, err := splitSheetPrefixedRange(rng)
 		if err != nil {
@@ -382,13 +390,10 @@ var DropdownDelete = common.Shortcut{
 		if _, err := resolveSpreadsheetToken(runtime); err != nil {
 			return err
 		}
-		ranges, err := validateDropdownRanges(runtime)
-		if err != nil {
+		// validateDropdownRanges enforces the shared maxBatchRanges cap.
+		if _, err := validateDropdownRanges(runtime); err != nil {
 			return err
 		}
-		if len(ranges) > 100 {
-			return sheetsValidationForFlag("ranges", "--ranges accepts at most 100 entries; got %d", len(ranges))
-		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -432,7 +437,8 @@ func dropdownBatchInput(runtime *common.RuntimeContext, token string, clear bool
 		}
 		prototype = map[string]interface{}{"data_validation": validation}
 	}
-	var ops []interface{}
+	ops := make([]interface{}, 0, len(ranges))
+	var totalCells int64
 	for _, rng := range ranges {
 		sheet, sub, err := splitSheetPrefixedRange(rng)
 		if err != nil {
@@ -442,6 +448,13 @@ func dropdownBatchInput(runtime *common.RuntimeContext, token string, clear bool
 		if err != nil {
 			return nil, sheetsValidationForFlag("range", "range %q: %v", rng, err)
 		}
+		if err := checkStampMatrixBudget("ranges", rng, rows, cols); err != nil {
+			return nil, err
+		}
+		totalCells += int64(rows) * int64(cols)
+		if err := checkBatchStampBudget(totalCells); err != nil {
+			return nil, err
+		}
 		cells := fillCellsMatrix(rows, cols, prototype)
 		ops = append(ops, map[string]interface{}{
 			"tool_name": "set_cell_range",
@@ -461,6 +474,25 @@ func dropdownBatchInput(runtime *common.RuntimeContext, token string, clear bool
 
 // ─── helpers resurrected from B3 (used here + future skills) ──────────
 
+// maxBatchRanges caps how many ranges a fan-out batch (+cells-batch-set-style /
+// +cells-batch-clear / +dropdown-update / +dropdown-delete) may carry, bounding
+// the number of ops materialized into one batch_update.
+const maxBatchRanges = 100
+
+// checkBatchStampBudget rejects a fan-out batch whose ranges materialize more
+// than maxStampMatrixCells cells in aggregate. A batch builds every range's
+// cells matrix up front, so the SUM across ranges is the real peak-memory bound
+// — the per-range checkStampMatrixBudget alone can't stop many ranges from
+// summing past it. totalCells is int64 to stay overflow-safe.
+func checkBatchStampBudget(totalCells int64) error {
+	if totalCells > maxStampMatrixCells {
+		return sheetsValidationForFlag("ranges",
+			"ranges expand to %d cells total, over the %d-cell safety cap; reduce the number or size of ranges",
+			totalCells, maxStampMatrixCells)
+	}
+	return nil
+}
+
 // validateDropdownRanges parses --ranges, requires every entry to carry a
 // sheet prefix, and returns the parsed list.
 func validateDropdownRanges(runtime *common.RuntimeContext) ([]string, error) {
@@ -490,6 +522,9 @@ func validateDropdownRanges(runtime *common.RuntimeContext) ([]string, error) {
 		}
 		out = append(out, s)
 	}
+	if len(out) > maxBatchRanges {
+		return nil, sheetsValidationForFlag("ranges", "--ranges accepts at most %d entries; got %d", maxBatchRanges, len(out))
+	}
 	return out, nil
 }
 

shortcuts/sheets/lark_sheet_formula_verify.go

@@ -0,0 +1,167 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/util"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ─── lark_sheet_formula_verify ───────────────────────────────────────
+//
+// Wraps verify_formula (read): scan formulas + cell error states across one
+// or more sub-sheets and aggregate Excel errors (#REF! / #DIV/0! / #VALUE! /
+// #NAME? / #NULL! / #NUM! / #N/A) plus compile failures (formula_errors)
+// into a recalc.py-shaped JSON status report. The contract is the single
+// AI self-check entry point for the R10 "write → verify zero-error"
+// invariant — see canonical-spec/references/lark_sheet_formula_verify/.
+
+// FormulaVerify wraps verify_formula. Sheet selection is optional (both
+// --sheet-id and --sheet-name are repeatable); when omitted, the tool scans
+// every visible sub-sheet's current_region.
+var FormulaVerify = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+formula-verify",
+	Description: "Scan formulas / cell errors and return a recalc.py-shaped status report (success / errors_found / partial).",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags:       flagsFor("+formula-verify"),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := resolveSpreadsheetToken(runtime); err != nil {
+			return err
+		}
+		if err := validateFormulaVerifySheetSelector(runtime); err != nil {
+			return err
+		}
+		return validateFormulaVerifyLimits(runtime)
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		return invokeToolDryRun(token, ToolKindRead, "verify_formula", formulaVerifyInput(runtime, token))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetTokenExec(runtime)
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindRead, "verify_formula", formulaVerifyInput(runtime, token))
+		if err != nil {
+			return err
+		}
+		runtime.Out(out, nil)
+		if runtime.Bool("exit-on-error") {
+			return formulaVerifyExitOnError(out)
+		}
+		return nil
+	},
+}
+
+// validateFormulaVerifySheetSelector enforces XOR-like guarantees on the
+// two multi-value selectors: at most one of --sheet-id / --sheet-name may be
+// non-empty (passing both is the high-frequency reflex confusion when the
+// caller cargo-cults the single-sheet shortcut signature). Both empty is the
+// documented "scan every visible sub-sheet" path. Control-char checks reuse
+// requireSheetSelector's logic on each item.
+func validateFormulaVerifySheetSelector(runtime *common.RuntimeContext) error {
+	ids := nonEmptySliceItems(runtime.StrSlice("sheet-id"))
+	names := nonEmptySliceItems(runtime.StrSlice("sheet-name"))
+	if len(ids) > 0 && len(names) > 0 {
+		return common.ValidationErrorf("--sheet-id and --sheet-name are mutually exclusive; pick one selector to identify sub-sheets").
+			WithParams(
+				sheetsInvalidParam("sheet-id", "mutually exclusive"),
+				sheetsInvalidParam("sheet-name", "mutually exclusive"),
+			)
+	}
+	for _, id := range ids {
+		if err := requireSheetSelector(id, ""); err != nil {
+			return err
+		}
+	}
+	for _, name := range names {
+		if err := requireSheetSelector("", name); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// validateFormulaVerifyLimits rejects non-positive caps so a misplaced 0 or
+// negative flag value can't silently degrade the scan (the server-side
+// default would otherwise mask the typo).
+func validateFormulaVerifyLimits(runtime *common.RuntimeContext) error {
+	if runtime.Changed("max-locations") && runtime.Int("max-locations") <= 0 {
+		return sheetsValidationForFlag("max-locations", "--max-locations must be > 0")
+	}
+	return nil
+}
+
+// nonEmptySliceItems trims and drops blanks from a repeated-flag value so
+// `--sheet-id ""` doesn't masquerade as a real entry.
+func nonEmptySliceItems(in []string) []string {
+	out := make([]string, 0, len(in))
+	for _, v := range in {
+		if trimmed := strings.TrimSpace(v); trimmed != "" {
+			out = append(out, trimmed)
+		}
+	}
+	return out
+}
+
+// formulaVerifyInput builds the verify_formula tool input map from CLI flags.
+// excel_id is required; everything else is optional per the schema.
+func formulaVerifyInput(runtime *common.RuntimeContext, token string) map[string]interface{} {
+	input := map[string]interface{}{
+		"excel_id": token,
+	}
+	if ids := nonEmptySliceItems(runtime.StrSlice("sheet-id")); len(ids) > 0 {
+		input["sheet_ids"] = ids
+	} else if names := nonEmptySliceItems(runtime.StrSlice("sheet-name")); len(names) > 0 {
+		// The verify_formula schema only declares sheet_ids; the facade
+		// accepts sheet_names as a parallel optional field so name-based
+		// selection works without forcing the caller to pre-resolve. Mirrors
+		// how the other read shortcuts pack both fields via
+		// sheetSelectorForToolInput.
+		input["sheet_names"] = names
+	}
+	if ranges := nonEmptySliceItems(runtime.StrSlice("range")); len(ranges) > 0 {
+		input["ranges"] = ranges
+	}
+	if runtime.Changed("max-locations") {
+		input["max_locations_per_error"] = runtime.Int("max-locations")
+	}
+	return input
+}
+
+// formulaVerifyExitOnError converts a verify_formula status into a non-zero
+// CLI exit when the caller passed --exit-on-error. status="errors_found"
+// is the only failure mode for this flag: "partial" means truncated but the
+// scanned slice is clean, and "success" is obviously clean. A missing /
+// unknown status is treated as a typed internal error because the tool's
+// schema guarantees the field and we don't want a silent zero-exit.
+func formulaVerifyExitOnError(out interface{}) error {
+	m, ok := out.(map[string]interface{})
+	if !ok {
+		return errs.NewInternalError(errs.SubtypeInvalidResponse,
+			"verify_formula: missing status field in tool output")
+	}
+	status, _ := m["status"].(string)
+	switch status {
+	case "success", "partial":
+		return nil
+	case "errors_found":
+		total, _ := util.ToFloat64(m["total_errors"])
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition,
+			"verify_formula: %d formula error(s) detected; resolve and re-run", int(total)).
+			WithHint("inspect error_summary[*] / compile_errors[*] in the JSON output, fix or wrap with IFERROR, then re-run +formula-verify until status=success")
+	default:
+		return errs.NewInternalError(errs.SubtypeInvalidResponse,
+			"verify_formula: unexpected status %q", status)
+	}
+}

shortcuts/sheets/lark_sheet_formula_verify_test.go

@@ -0,0 +1,213 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+)
+
+// TestFormulaVerify_DryRun pins the wire shape verify_formula sends for the
+// common input combinations: no selector (workbook-wide scan), explicit
+// sheet_ids, explicit ranges, and the optional max_locations_per_error
+// field. The test exercises the One-OpenAPI body
+// directly so the schema field names stay locked to the canonical
+// tool-schemas.json verify_formula node.
+func TestFormulaVerify_DryRun(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		args      []string
+		wantInput map[string]interface{}
+	}{
+		{
+			name: "no selector — workbook-wide scan defaults",
+			args: []string{"--url", testURL},
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+			},
+		},
+		{
+			name: "sheet_ids multi via repeat",
+			args: []string{"--url", testURL, "--sheet-id", testSheetID, "--sheet-id", testSheetID2},
+			wantInput: map[string]interface{}{
+				"excel_id":  testToken,
+				"sheet_ids": []interface{}{testSheetID, testSheetID2},
+			},
+		},
+		{
+			name: "sheet_names multi via comma",
+			args: []string{"--url", testURL, "--sheet-name", "Sheet1,Sheet2"},
+			wantInput: map[string]interface{}{
+				"excel_id":    testToken,
+				"sheet_names": []interface{}{"Sheet1", "Sheet2"},
+			},
+		},
+		{
+			name: "ranges + max_locations",
+			args: []string{
+				"--url", testURL,
+				"--range", "A1:Z200",
+				"--range", "AA1:AZ100",
+				"--max-locations", "5",
+			},
+			wantInput: map[string]interface{}{
+				"excel_id":                testToken,
+				"ranges":                  []interface{}{"A1:Z200", "AA1:AZ100"},
+				"max_locations_per_error": float64(5),
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			body := parseDryRunBody(t, FormulaVerify, tt.args)
+			got := decodeToolInput(t, body, "verify_formula")
+			assertInputEquals(t, got, tt.wantInput)
+		})
+	}
+}
+
+// TestFormulaVerify_DryRunInvokeReadPath confirms the request hits
+// invoke_read (read scope) and not invoke_write — a scope mismatch here would
+// surface as a 403 from the gateway.
+func TestFormulaVerify_DryRunInvokeReadPath(t *testing.T) {
+	t.Parallel()
+	calls := parseDryRunAPI(t, FormulaVerify, []string{"--url", testURL})
+	if len(calls) == 0 {
+		t.Fatalf("dry-run produced no api calls")
+	}
+	call, _ := calls[0].(map[string]interface{})
+	url, _ := call["url"].(string)
+	if !strings.HasSuffix(url, "/tools/invoke_read") {
+		t.Errorf("verify_formula must hit invoke_read; got url=%q", url)
+	}
+	if want := "/open-apis/sheet_ai/v2/spreadsheets/" + testToken + "/tools/invoke_read"; url != want {
+		t.Errorf("url = %q, want %q", url, want)
+	}
+}
+
+// TestFormulaVerify_RejectsBothSelectors locks the "at most one selector"
+// rule on the two multi-value flags. Both empty is the documented
+// workbook-wide scan path, so we only reject the both-supplied case.
+func TestFormulaVerify_RejectsBothSelectors(t *testing.T) {
+	t.Parallel()
+	_, _, err := runShortcutCapturingErr(t, FormulaVerify, []string{
+		"--url", testURL,
+		"--sheet-id", testSheetID,
+		"--sheet-name", "Sheet1",
+		"--dry-run",
+	})
+	ve := requireValidation(t, err, "mutually exclusive")
+	gotParams := map[string]bool{}
+	for _, p := range ve.Params {
+		gotParams[p.Name] = true
+	}
+	if !gotParams["--sheet-id"] || !gotParams["--sheet-name"] {
+		t.Errorf("params = %#v, want both --sheet-id and --sheet-name flagged", ve.Params)
+	}
+}
+
+// TestFormulaVerify_RejectsNonPositiveLimits guards against typos like
+// `--max-locations 0`, which would otherwise be silently swallowed by the
+// "explicit value but unset" comparison in the input builder.
+func TestFormulaVerify_RejectsNonPositiveLimits(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{
+			name: "max-locations=0",
+			args: []string{"--url", testURL, "--max-locations", "0"},
+			want: "--max-locations must be > 0",
+		},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			t.Parallel()
+			_, _, err := runShortcutCapturingErr(t, FormulaVerify, append(c.args, "--dry-run"))
+			requireValidation(t, err, c.want)
+		})
+	}
+}
+
+// TestFormulaVerifyExitOnError_StatusMatrix locks the --exit-on-error
+// contract: success/partial → no error; errors_found → typed validation
+// error with SubtypeFailedPrecondition; missing or unknown status →
+// typed internal error so a silent zero-exit can never happen.
+func TestFormulaVerifyExitOnError_StatusMatrix(t *testing.T) {
+	t.Parallel()
+
+	t.Run("success returns no error", func(t *testing.T) {
+		t.Parallel()
+		if err := formulaVerifyExitOnError(map[string]interface{}{"status": "success"}); err != nil {
+			t.Fatalf("success path returned err: %v", err)
+		}
+	})
+
+	t.Run("partial returns no error", func(t *testing.T) {
+		t.Parallel()
+		if err := formulaVerifyExitOnError(map[string]interface{}{"status": "partial", "has_more": true}); err != nil {
+			t.Fatalf("partial path returned err: %v", err)
+		}
+	})
+
+	t.Run("errors_found yields failed_precondition with count", func(t *testing.T) {
+		t.Parallel()
+		err := formulaVerifyExitOnError(map[string]interface{}{
+			"status":       "errors_found",
+			"total_errors": float64(7),
+		})
+		if err == nil {
+			t.Fatal("expected error, got nil")
+		}
+		var ve *errs.ValidationError
+		if !errors.As(err, &ve) {
+			t.Fatalf("error = %T %v, want *errs.ValidationError", err, err)
+		}
+		if ve.Subtype != errs.SubtypeFailedPrecondition {
+			t.Errorf("subtype = %q, want %q", ve.Subtype, errs.SubtypeFailedPrecondition)
+		}
+		if !strings.Contains(ve.Message, "7 formula error") {
+			t.Errorf("message %q must surface the error count", ve.Message)
+		}
+		if ve.Hint == "" {
+			t.Errorf("hint must be set so AI agents know to re-run after fixes")
+		}
+	})
+
+	t.Run("unknown status maps to internal/invalid_response", func(t *testing.T) {
+		t.Parallel()
+		err := formulaVerifyExitOnError(map[string]interface{}{"status": "weird"})
+		if err == nil {
+			t.Fatal("expected error, got nil")
+		}
+		p, ok := errs.ProblemOf(err)
+		if !ok {
+			t.Fatalf("expected typed problem, got %T %v", err, err)
+		}
+		if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
+			t.Errorf("category/subtype = %q/%q, want internal/invalid_response", p.Category, p.Subtype)
+		}
+	})
+
+	t.Run("non-object output maps to internal/invalid_response", func(t *testing.T) {
+		t.Parallel()
+		err := formulaVerifyExitOnError("oops")
+		p, ok := errs.ProblemOf(err)
+		if !ok {
+			t.Fatalf("expected typed problem, got %T %v", err, err)
+		}
+		if p.Category != errs.CategoryInternal || p.Subtype != errs.SubtypeInvalidResponse {
+			t.Errorf("category/subtype = %q/%q, want internal/invalid_response", p.Category, p.Subtype)
+		}
+	})
+}

shortcuts/sheets/lark_sheet_history_list.go

@@ -0,0 +1,97 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ─── lark_sheet_history (BE-1: +history-list) ─────────────────────────
+//
+// Wraps the facade-agg `history_list` tool (read) behind the One-OpenAPI
+// invoke_read endpoint. The tool returns a sheet's version history. The
+// facade-agg tool already performs the response transform (minor_histories
+// trim / id → history_version_id / 4-field projection / RFC3339 create_time),
+// so the CLI passes the tool output straight through and does NOT re-implement
+// the transform client-side.
+//
+// History is workbook-level (no sheet selector), mirroring +workbook-info:
+// the only locator is --url / --spreadsheet-token (XOR), with --token accepted
+// as a parse-time alias for --spreadsheet-token via the shared PostMount hook.
+//
+// Flags are declared inline here rather than via flagsFor(): the generated
+// flag_defs_gen.go / data/flag-defs.json are synced from sheet-skill-spec
+// (BE-3) and must not be hand-edited, so this hand-written shortcut owns its
+// own flag set. The two locator flags match +workbook-info's shape exactly.
+
+// historyLocatorFlags is the --url / --spreadsheet-token XOR locator pair
+// shared by the three history shortcuts. Mirrors +workbook-info's flag-defs
+// entry; XOR is enforced in Validate via parseSpreadsheetRef, not by Required.
+func historyLocatorFlags() []common.Flag {
+	return []common.Flag{
+		{Name: "url", Type: "string", Desc: "Spreadsheet locator (a /sheets/ or /wiki/ URL)."},
+		{Name: "spreadsheet-token", Type: "string", Desc: "Spreadsheet locator (raw spreadsheet token)."},
+	}
+}
+
+// HistoryList wraps the history_list tool: list a spreadsheet's history
+// versions. Each item carries history_version_id / create_time / action /
+// all_block_revision (projected server-side). An empty sheet yields an empty
+// list and exit 0.
+//
+// Backward pagination: --end-version (optional int) maps to the tool's
+// `end_version` parameter. Omit on the first call to fetch the latest page.
+// On subsequent pages pass the previous response's next_end_version as
+// --end-version. The tool returns next_end_version + has_more only when
+// more history exists; both fields are absent at the earliest page.
+var HistoryList = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+history-list",
+	Description: "List a spreadsheet's edit history versions (history_version_id, create_time, action, all_block_revision).",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: append(historyLocatorFlags(),
+		common.Flag{Name: "end-version", Type: "int", Desc: "Max version to query (descending pagination). Omit on the first call; pass the previous response's next_end_version on subsequent pages."},
+	),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := resolveSpreadsheetToken(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		return invokeToolDryRun(token, ToolKindRead, "history_list", historyListInput(runtime, token))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetTokenExec(runtime)
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindRead, "history_list", historyListInput(runtime, token))
+		if err != nil {
+			return err
+		}
+		// Pass the tool output through verbatim — facade-agg already shaped it.
+		runtime.Out(out, nil)
+		return nil
+	},
+	Tips: []string{
+		"Capture a history_version_id from the result to feed +history-revert.",
+		"For older history, capture next_end_version from the response and pass it as --end-version on the next call (omitted by the server when the earliest page is reached).",
+	},
+}
+
+// historyListInput composes the history_list tool input. --end-version is
+// optional: include it only when explicitly set so the server treats absence
+// as "first page (latest)".
+func historyListInput(runtime *common.RuntimeContext, token string) map[string]interface{} {
+	in := map[string]interface{}{"excel_id": token}
+	if runtime.Changed("end-version") {
+		in["end_version"] = runtime.Int("end-version")
+	}
+	return in
+}

shortcuts/sheets/lark_sheet_history_revert.go

@@ -0,0 +1,196 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"context"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ─── lark_sheet_history (BE-2: +history-revert / +history-revert-status) ──
+//
+// Two thin callTool wrappers over the facade-agg history tools:
+//   - +history-revert        → history_revert        (write) — async revert
+//   - +history-revert-status → history_revert_status (read)  — poll outcome
+//
+// Both target a single history version via --history-version-id (the id
+// surfaced by +history-list). Revert is asynchronous: it returns a receipt /
+// transaction id that +history-revert-status then polls, distinguishing
+// in-progress / success / failure from the tool output (passed through
+// verbatim — no client-side shaping).
+//
+// ⚠️ Backend state: the facade-agg history_revert / history_revert_status
+// tools are registered but their downstream RPC wiring is a DEFERRED
+// follow-up; today they return a "not wired yet" guard error from the gateway,
+// which surfaces here as a normal tool error. These CLI shortcuts are correct
+// thin wrappers and will work end-to-end once the backend follow-up lands —
+// this is NOT a CLI blocker. See self_check.md.
+//
+// Flags are declared inline (historyLocatorFlags + history-version-id) rather
+// than via flagsFor(), because flag_defs_gen.go / data/flag-defs.json are
+// synced from sheet-skill-spec (BE-3) and must not be hand-edited.
+
+// historyVersionIDFlag is the target-version selector shared by +history-revert.
+// Required at the cli surface (cobra MarkFlagRequired): a missing value yields
+// cobra's standard "required flag(s) \"history-version-id\" not set" message
+// before Validate runs. We still trim + reject control-chars in Validate to
+// reject empty strings ("--history-version-id "" "), which cobra accepts.
+func historyVersionIDFlag() common.Flag {
+	return common.Flag{
+		Name:     "history-version-id",
+		Type:     "string",
+		Required: true,
+		Desc:     "History version to act on (from +history-list).",
+	}
+}
+
+func historyRevertFlags() []common.Flag {
+	return append(historyLocatorFlags(), historyVersionIDFlag())
+}
+
+// validateHistoryVersionID enforces the required, control-char-clean
+// --history-version-id. Returns the trimmed value so callers reuse it.
+func validateHistoryVersionID(runtime *common.RuntimeContext) (string, error) {
+	id := strings.TrimSpace(runtime.Str("history-version-id"))
+	if id == "" {
+		return "", sheetsValidationForFlag("history-version-id", "--history-version-id is required")
+	}
+	return id, nil
+}
+
+func historyRevertInput(token, versionID string) map[string]interface{} {
+	return map[string]interface{}{
+		"excel_id":           token,
+		"history_version_id": versionID,
+	}
+}
+
+// transactionIDFlag is the async-revert receipt selector used by
+// +history-revert-status: the transaction_id returned by +history-revert (NOT a
+// history version id — the facade-agg status tool keys on transaction_id).
+// Required at the cli surface (cobra MarkFlagRequired) — same gating model as
+// historyVersionIDFlag. Validate still trims + rejects empty/control-char
+// values to catch the "--transaction-id ''" cobra-accepts-but-empty case.
+func transactionIDFlag() common.Flag {
+	return common.Flag{
+		Name:     "transaction-id",
+		Type:     "string",
+		Required: true,
+		Desc:     "Async revert transaction id (from +history-revert).",
+	}
+}
+
+func historyRevertStatusFlags() []common.Flag {
+	return append(historyLocatorFlags(), transactionIDFlag())
+}
+
+// validateTransactionID enforces the required, trimmed --transaction-id and
+// returns it for reuse.
+func validateTransactionID(runtime *common.RuntimeContext) (string, error) {
+	id := strings.TrimSpace(runtime.Str("transaction-id"))
+	if id == "" {
+		return "", sheetsValidationForFlag("transaction-id", "--transaction-id is required")
+	}
+	return id, nil
+}
+
+func historyRevertStatusInput(token, transactionID string) map[string]interface{} {
+	return map[string]interface{}{
+		"excel_id":       token,
+		"transaction_id": transactionID,
+	}
+}
+
+// HistoryRevert wraps the history_revert tool (write): asynchronously revert a
+// spreadsheet to the given history version. --history-version-id is required
+// at the cli surface (cobra MarkFlagRequired); a missing flag fails before
+// Validate runs with cobra's standard "required flag(s)" error (which the
+// dispatcher classifies as a typed *errs.ValidationError, exit 2). We still
+// trim + reject empty / control-char values in Validate to catch the
+// "--history-version-id ''" cobra-accepts-but-empty case.
+var HistoryRevert = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+history-revert",
+	Description: "Revert a spreadsheet to a given history version (asynchronous; poll with +history-revert-status).",
+	Risk:        "write",
+	Scopes:      []string{"sheets:spreadsheet:write_only"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags:       historyRevertFlags(),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := resolveSpreadsheetToken(runtime); err != nil {
+			return err
+		}
+		_, err := validateHistoryVersionID(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		versionID := strings.TrimSpace(runtime.Str("history-version-id"))
+		return invokeToolDryRun(token, ToolKindWrite, "history_revert", historyRevertInput(token, versionID))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetTokenExec(runtime)
+		if err != nil {
+			return err
+		}
+		versionID, err := validateHistoryVersionID(runtime)
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindWrite, "history_revert", historyRevertInput(token, versionID))
+		if err != nil {
+			return err
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+	Tips: []string{
+		"Revert is asynchronous — pass the returned id to +history-revert-status to track in-progress / success / failure.",
+	},
+}
+
+// HistoryRevertStatus wraps the history_revert_status tool (read): poll the
+// outcome of a prior +history-revert. The tool output distinguishes
+// in-progress / success / failure and is passed through verbatim.
+var HistoryRevertStatus = common.Shortcut{
+	Service:     "sheets",
+	Command:     "+history-revert-status",
+	Description: "Poll the status of a history revert (in-progress / success / failure).",
+	Risk:        "read",
+	Scopes:      []string{"sheets:spreadsheet:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags:       historyRevertStatusFlags(),
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := resolveSpreadsheetToken(runtime); err != nil {
+			return err
+		}
+		_, err := validateTransactionID(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		token, _ := resolveSpreadsheetToken(runtime)
+		txnID := strings.TrimSpace(runtime.Str("transaction-id"))
+		return invokeToolDryRun(token, ToolKindRead, "history_revert_status", historyRevertStatusInput(token, txnID))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		token, err := resolveSpreadsheetTokenExec(runtime)
+		if err != nil {
+			return err
+		}
+		txnID, err := validateTransactionID(runtime)
+		if err != nil {
+			return err
+		}
+		out, err := callTool(ctx, runtime, token, ToolKindRead, "history_revert_status", historyRevertStatusInput(token, txnID))
+		if err != nil {
+			return err
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+}

shortcuts/sheets/lark_sheet_history_test.go

@@ -0,0 +1,167 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// TestHistoryShortcuts_DryRun asserts each history shortcut targets the right
+// facade-agg tool, routes through the correct read/write invoke endpoint, and
+// builds the expected tool input (excel_id always; history_version_id for the
+// revert pair).
+func TestHistoryShortcuts_DryRun(t *testing.T) {
+	t.Parallel()
+
+	const versionID = "histVER123"
+	const txnID = "txn-abc-123"
+
+	tests := []struct {
+		name      string
+		sc        common.Shortcut
+		args      []string
+		toolName  string
+		wantPath  string // invoke_read | invoke_write suffix
+		wantInput map[string]interface{}
+	}{
+		{
+			name:     "+history-list via --url",
+			sc:       HistoryList,
+			args:     []string{"--url", testURL},
+			toolName: "history_list",
+			wantPath: "invoke_read",
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+			},
+		},
+		{
+			name:     "+history-list via --spreadsheet-token",
+			sc:       HistoryList,
+			args:     []string{"--spreadsheet-token", testToken},
+			toolName: "history_list",
+			wantPath: "invoke_read",
+			wantInput: map[string]interface{}{
+				"excel_id": testToken,
+			},
+		},
+		{
+			name:     "+history-list paginates with --end-version",
+			sc:       HistoryList,
+			args:     []string{"--url", testURL, "--end-version", "12345"},
+			toolName: "history_list",
+			wantPath: "invoke_read",
+			wantInput: map[string]interface{}{
+				"excel_id":    testToken,
+				"end_version": float64(12345), // post-JSON-unmarshal numeric type
+			},
+		},
+		{
+			name:     "+history-revert routes to invoke_write with version id",
+			sc:       HistoryRevert,
+			args:     []string{"--url", testURL, "--history-version-id", versionID},
+			toolName: "history_revert",
+			wantPath: "invoke_write",
+			wantInput: map[string]interface{}{
+				"excel_id":           testToken,
+				"history_version_id": versionID,
+			},
+		},
+		{
+			name:     "+history-revert-status routes to invoke_read with transaction id",
+			sc:       HistoryRevertStatus,
+			args:     []string{"--url", testURL, "--transaction-id", txnID},
+			toolName: "history_revert_status",
+			wantPath: "invoke_read",
+			wantInput: map[string]interface{}{
+				"excel_id":       testToken,
+				"transaction_id": txnID,
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			callURL := dryRunFirstCallURL(t, tt.sc, tt.args)
+			if !containsSuffix(callURL, tt.wantPath) {
+				t.Errorf("invoke url = %q, want suffix %q", callURL, tt.wantPath)
+			}
+			body := parseDryRunBody(t, tt.sc, tt.args)
+			got := decodeToolInput(t, body, tt.toolName)
+			assertInputEquals(t, got, tt.wantInput)
+		})
+	}
+}
+
+// TestHistoryRevert_MissingRequiredFlag asserts each shortcut rejects a
+// missing required selector before any request is sent, with two distinct
+// gates by design:
+//
+//   - +history-revert: --history-version-id is cobra-required (Required=true
+//     in the flag def → MarkFlagRequired). cobra refuses the call before
+//     Validate runs with a plain "required flag(s)" error; the cmd dispatcher
+//     classifies it as a typed *errs.ValidationError (invalid_argument, exit 2).
+//     The test rig invokes the shortcut via cmd.Execute and observes the raw
+//     cobra error directly (no dispatcher wrap), so we assert the cobra text
+//     contract instead of the typed envelope.
+//
+//   - +history-revert-status: --transaction-id is cobra-optional;
+//     requiredness is enforced inside Validate so we still get a typed,
+//     flag-tagged *errs.ValidationError with Param="--transaction-id".
+func TestHistoryRevert_MissingRequiredFlag(t *testing.T) {
+	t.Parallel()
+
+	t.Run(HistoryRevert.Command, func(t *testing.T) {
+		t.Parallel()
+		_, _, err := runShortcutCapturingErr(t, HistoryRevert, []string{"--url", testURL})
+		if err == nil {
+			t.Fatalf("%s: expected error for missing --history-version-id", HistoryRevert.Command)
+		}
+		msg := err.Error()
+		if !strings.Contains(msg, "required flag(s)") || !strings.Contains(msg, "history-version-id") {
+			t.Fatalf("%s: cobra error = %q, want substrings 'required flag(s)' and 'history-version-id'", HistoryRevert.Command, msg)
+		}
+	})
+
+	t.Run(HistoryRevertStatus.Command, func(t *testing.T) {
+		t.Parallel()
+		_, _, err := runShortcutCapturingErr(t, HistoryRevertStatus, []string{"--url", testURL})
+		if err == nil {
+			t.Fatalf("%s: expected error for missing --transaction-id", HistoryRevertStatus.Command)
+		}
+		msg := err.Error()
+		if !strings.Contains(msg, "required flag(s)") || !strings.Contains(msg, "transaction-id") {
+			t.Fatalf("%s: cobra error = %q, want substrings 'required flag(s)' and 'transaction-id'", HistoryRevertStatus.Command, msg)
+		}
+	})
+}
+
+// dryRunFirstCallURL runs the shortcut in --dry-run and returns the first
+// api call's url, so tests can assert read vs. write endpoint routing.
+func dryRunFirstCallURL(t *testing.T, sc common.Shortcut, args []string) string {
+	t.Helper()
+	out, err := runShortcut(t, sc, append(args, "--dry-run"))
+	if err != nil {
+		t.Fatalf("dry-run failed: %v\noutput=%s", err, out)
+	}
+	dryRun := decodeDryRunRaw(t, out)
+	calls, ok := dryRun["api"].([]interface{})
+	if !ok || len(calls) == 0 {
+		t.Fatalf("dry-run api array empty or wrong shape: %#v", dryRun)
+	}
+	call, _ := calls[0].(map[string]interface{})
+	url, _ := call["url"].(string)
+	return url
+}
+
+func containsSuffix(s, sub string) bool {
+	for i := 0; i+len(sub) <= len(s); i++ {
+		if s[i:i+len(sub)] == sub {
+			return true
+		}
+	}
+	return false
+}

shortcuts/sheets/lark_sheet_object_crud.go

@@ -861,10 +861,10 @@ func newFloatImageWriteShortcut(command, description, op string, withIDFlag, isH
 				manageBody, _ := buildToolBody("manage_float_image_object", input)
 				return common.NewDryRunAPI().
 					POST("/open-apis/drive/v1/medias/upload_all").
-					Desc("upload local image to drive (parent_type=sheet_image)").
+					Desc("upload local image to drive (parent_type=" + sheetMediaParentType(token) + ")").
 					Body(map[string]interface{}{
 						"file_name":   floatImageName(runtime),
-						"parent_type": "sheet_image",
+						"parent_type": sheetMediaParentType(token),
 						"parent_node": token,
 						"size":        "<file_size>",
 						"file":        "@" + img,
@@ -918,13 +918,7 @@ func uploadFloatImageIfLocal(runtime *common.RuntimeContext, spreadsheetToken st
 	if err != nil {
 		return "", sheetsInputStatError("image", err)
 	}
-	return common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
-		FilePath:   img,
-		FileName:   floatImageName(runtime),
-		FileSize:   info.Size(),
-		ParentType: "sheet_image",
-		ParentNode: &spreadsheetToken,
-	})
+	return uploadSheetImage(runtime, spreadsheetToken, img, floatImageName(runtime), info.Size())
 }
 
 func floatImageWriteInput(runtime flagView, token, sheetID, sheetName, op string, withIDFlag bool, uploadedImageToken string) (map[string]interface{}, error) {

shortcuts/sheets/lark_sheet_table_io.go

@@ -382,6 +382,32 @@ func (p *tablePayload) validate() error {
 			return common.ValidationErrorf("--sheets[%d] %q: mode %q is invalid (want \"overwrite\" or \"append\")", i, s.Name, s.Mode)
 		}
 	}
+	return p.checkCellBudget()
+}
+
+// maxTablePutCells bounds how many cells a single +table-put / +workbook-create
+// write may materialize. Unlike the fan-out stamp cap (maxStampMatrixCells),
+// these cells come from the caller's own --sheets/--values payload rather than a
+// range blow-up, so this is a generous OOM guardrail, not a usability limit:
+// buildSheetMatrix builds the whole rows×cols matrix of per-cell maps in memory
+// before slicing it into tablePutMaxCellsPerWrite-sized writes, so an unbounded
+// payload (2.6M cells ≈ 900MB heap, doubled again by json.Marshal) OOMs the
+// process before the first write leaves.
+const maxTablePutCells = 1_000_000
+
+// checkCellBudget rejects a payload whose total materialized cell count across
+// all sheets exceeds maxTablePutCells. Counted in int64 to stay overflow-safe on
+// pathological row/column counts.
+func (p *tablePayload) checkCellBudget() error {
+	var total int64
+	for i := range p.Sheets {
+		total += int64(len(p.Sheets[i].Rows)) * int64(len(p.Sheets[i].Columns))
+	}
+	if total > maxTablePutCells {
+		return common.ValidationErrorf(
+			"--sheets/--values cover %d cells total, over the %d-cell safety cap; split the write across smaller payloads",
+			total, maxTablePutCells)
+	}
 	return nil
 }
 

shortcuts/sheets/lark_sheet_workbook.go

@@ -123,6 +123,26 @@ func sheetCreateInput(runtime flagView, token string) (map[string]interface{}, e
 	if strings.TrimSpace(runtime.Str("title")) == "" {
 		return nil, common.ValidationErrorf("--title is required")
 	}
+	// --type bitable 建一张空白多维表格子表（operation=create_bitable）；默认 sheet 为普通
+	// 电子表格子表。bitable 子表内容编辑走 lark-base 命令，row-count/col-count 不适用。
+	sheetType := strings.TrimSpace(runtime.Str("type"))
+	if sheetType == "" {
+		sheetType = "sheet"
+	}
+	if sheetType != "sheet" && sheetType != "bitable" {
+		return nil, common.ValidationErrorf("--type must be 'sheet' or 'bitable'")
+	}
+	if sheetType == "bitable" {
+		input := map[string]interface{}{
+			"excel_id":   token,
+			"operation":  "create_bitable",
+			"sheet_name": strings.TrimSpace(runtime.Str("title")),
+		}
+		if runtime.Changed("index") {
+			input["target_index"] = runtime.Int("index")
+		}
+		return input, nil
+	}
 	if n := runtime.Int("row-count"); n < 0 || n > 50000 {
 		return nil, common.ValidationErrorf("--row-count must be between 0 and 50000")
 	}
@@ -836,13 +856,19 @@ func buildValuesPayload(runtime flagView, sheetStyles *workbookCreateSheetStyles
 		cols[i] = tableColumnSpec{Name: fmt.Sprintf("col%d", i+1)} // type-less
 	}
 	noHeader := false
-	return &tablePayload{Sheets: []tableSheetSpec{{
+	payload := &tablePayload{Sheets: []tableSheetSpec{{
 		Name:    valuesSheetName,
 		Mode:    "overwrite",
 		Header:  &noHeader,
 		Columns: cols,
 		Rows:    rows,
-	}}}, nil
+	}}}
+	// --values bypasses tablePayload.validate(), so enforce the cell budget here
+	// too — otherwise a giant --values array materializes unbounded.
+	if err := payload.checkCellBudget(); err != nil {
+		return nil, err
+	}
+	return payload, nil
 }
 
 // parseValuesRows decodes --values (JSON 2D array, with @file/stdin already
@@ -1246,7 +1272,7 @@ func normalizeWorkbookCreateStyleObject(in map[string]interface{}, path string)
 
 func workbookCreateCellStyleField(name string) bool {
 	switch name {
-	case "font_color", "font_size", "font_weight", "font_style", "font_line",
+	case "font_color", "font_family", "font_size", "font_weight", "font_style", "font_line",
 		"background_color", "horizontal_alignment", "vertical_alignment",
 		"number_format", "word_wrap":
 		return true

shortcuts/sheets/lark_sheet_write_cells.go

@@ -111,10 +111,10 @@ func cellsSetInput(runtime flagView, token, sheetID, sheetName string) (map[stri
 
 // CellsSetStyle stamps a single style block across every cell in --range.
 // Style is composed from a dozen flat flags (background-color, font-color,
-// font-size, font-style, font-weight, font-line, horizontal-alignment,
-// vertical-alignment, word-wrap, number-format) plus --border-styles for
-// the only field that still needs a nested object. At least one flag must
-// be set.
+// font-family, font-size, font-style, font-weight, font-line,
+// horizontal-alignment, vertical-alignment, word-wrap, number-format) plus
+// --border-styles for the only field that still needs a nested object. At
+// least one flag must be set.
 var CellsSetStyle = common.Shortcut{
 	Service:     "sheets",
 	Command:     "+cells-set-style",
@@ -165,6 +165,9 @@ func cellsSetStyleInput(runtime flagView, token, sheetID, sheetName string) (map
 	if err != nil {
 		return nil, sheetsValidationForFlag("range", "--range %q: %v", rangeStr, err)
 	}
+	if err := checkStampMatrixBudget("range", rangeStr, rows, cols); err != nil {
+		return nil, err
+	}
 	if err := requireAnyStyleFlag(runtime); err != nil {
 		return nil, err
 	}
@@ -450,6 +453,9 @@ func dropdownSetInput(runtime flagView, token, sheetID, sheetName string) (map[s
 	if err != nil {
 		return nil, sheetsValidationForFlag("range", "--range %q: %v", rangeStr, err)
 	}
+	if err := checkStampMatrixBudget("range", rangeStr, rows, cols); err != nil {
+		return nil, err
+	}
 	validation, err := buildDropdownValidation(runtime)
 	if err != nil {
 		return nil, err
@@ -692,9 +698,30 @@ func letterToColumnIndex(letters string) int {
 	return n - 1
 }
 
+// maxStampMatrixCells bounds how many per-cell maps a fan-out / stamp shortcut
+// will materialize from a single A1 range. The backing tools take an explicit
+// cells matrix, so the CLI must expand a range like "A1:Z100000" into rows×cols
+// maps before sending it — an unbounded blow-up (2.6M cells ≈ 900MB heap, then
+// doubled again by json.Marshal) that OOMs the process before the request even
+// leaves. 200000 matches the documented --max-cells safety cap.
+const maxStampMatrixCells = 200000
+
+// checkStampMatrixBudget rejects a range whose materialized cell count would
+// exceed maxStampMatrixCells, before fillCellsMatrix allocates it. rows*cols is
+// computed in int64 to stay safe against overflow on pathological ranges.
+func checkStampMatrixBudget(flagName, rangeStr string, rows, cols int) error {
+	if total := int64(rows) * int64(cols); total > maxStampMatrixCells {
+		return sheetsValidationForFlag(flagName,
+			"range %q covers %d cells, over the %d-cell safety cap; narrow the range or split it across smaller ranges",
+			rangeStr, total, maxStampMatrixCells)
+	}
+	return nil
+}
+
 // fillCellsMatrix returns a rows×cols matrix where every cell is the same
 // (shallow-copied) prototype map. Use for fan-out shortcuts that stamp a
 // single attribute (style / data_validation) across an entire range.
+// Callers MUST gate the dimensions through checkStampMatrixBudget first.
 func fillCellsMatrix(rows, cols int, prototype map[string]interface{}) [][]interface{} {
 	cells := make([][]interface{}, rows)
 	for r := range cells {
@@ -791,10 +818,10 @@ var CellsSetImage = common.Shortcut{
 		})
 		return common.NewDryRunAPI().
 			POST("/open-apis/drive/v1/medias/upload_all").
-			Desc("upload local image to drive (parent_type=sheet_image)").
+			Desc("upload local image to drive (parent_type=" + sheetMediaParentType(token) + ")").
 			Body(map[string]interface{}{
 				"file_name":   fileName,
-				"parent_type": "sheet_image",
+				"parent_type": sheetMediaParentType(token),
 				"parent_node": token,
 				"size":        "<file_size>",
 				"file":        "@" + imgPath,
@@ -832,13 +859,7 @@ var CellsSetImage = common.Shortcut{
 				WithParam("--image").
 				WithCause(err)
 		}
-		fileToken, err := common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
-			FilePath:   imgPath,
-			FileName:   fileName,
-			FileSize:   info.Size(),
-			ParentType: "sheet_image",
-			ParentNode: &token,
-		})
+		fileToken, err := uploadSheetImage(runtime, token, imgPath, fileName, info.Size())
 		if err != nil {
 			return err
 		}

shortcuts/sheets/lark_sheet_write_cells_test.go

@@ -496,6 +496,31 @@ func TestCellsSetImage_DryRun(t *testing.T) {
 	}
 }
 
+// TestCellsSetImage_DryRunOfficeParentType confirms that an imported "office"
+// spreadsheet (token prefixed with "fake_office_") uploads with
+// parent_type=office_sheet_file instead of the native sheet_image, and that the
+// preview's parent_node carries the same token.
+func TestCellsSetImage_DryRunOfficeParentType(t *testing.T) {
+	t.Parallel()
+	const officeToken = "fake_office_abc123"
+	calls := parseDryRunAPI(t, CellsSetImage, []string{
+		"--spreadsheet-token", officeToken, "--sheet-id", testSheetID,
+		"--range", "A1",
+		"--image", "./README.md", // any existing-shaped path; dry-run skips stat
+	})
+	if len(calls) != 2 {
+		t.Fatalf("api calls = %d, want 2 (upload + set_cell_range)", len(calls))
+	}
+	upload := calls[0].(map[string]interface{})
+	ubody, _ := upload["body"].(map[string]interface{})
+	if ubody["parent_type"] != officeSheetFileParentType {
+		t.Errorf("parent_type = %v, want %s", ubody["parent_type"], officeSheetFileParentType)
+	}
+	if ubody["parent_node"] != officeToken {
+		t.Errorf("parent_node = %v, want %s", ubody["parent_node"], officeToken)
+	}
+}
+
 func TestCellsSetImage_RangeMustBeSingleCell(t *testing.T) {
 	t.Parallel()
 	_, _, err := runShortcutCapturingErr(t, CellsSetImage, []string{

shortcuts/sheets/sheet_media_parent_type_test.go

@@ -0,0 +1,192 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"io/fs"
+	"mime"
+	"mime/multipart"
+	"os"
+	"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/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// TestSheetMediaParentType pins the token→parent_type mapping that every
+// sheets image-upload entry point funnels through. Native spreadsheet tokens
+// use "sheet_image"; imported "office" spreadsheets carry a "fake_office_"
+// synthetic token and must upload with "office_sheet_file".
+func TestSheetMediaParentType(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name  string
+		token string
+		want  string
+	}{
+		{"native spreadsheet token", "shtcnABC123", sheetImageParentType},
+		{"empty token", "", sheetImageParentType},
+		{"office imported token", "fake_office_abc123", officeSheetFileParentType},
+		{"office token, only the prefix", fakeOfficeTokenPrefix, officeSheetFileParentType},
+		{"prefix mid-string is not matched", "shtfake_office_abc", sheetImageParentType},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			if got := sheetMediaParentType(tc.token); got != tc.want {
+				t.Fatalf("sheetMediaParentType(%q) = %q, want %q", tc.token, got, tc.want)
+			}
+		})
+	}
+}
+
+// TestUploadSheetImage_ParentType exercises the uploadSheetImage collector end
+// to end (the Execute path the dry-run tests don't reach), asserting the
+// parent_type that actually goes out on the wire is derived from the token: a
+// native spreadsheet uploads as sheet_image, an imported "office" spreadsheet
+// (fake_office_-prefixed token) as office_sheet_file.
+func TestUploadSheetImage_ParentType(t *testing.T) {
+	cases := []struct {
+		name           string
+		token          string
+		wantParentType string
+	}{
+		{"native spreadsheet", "shtcnTOK123", sheetImageParentType},
+		{"office imported spreadsheet", "fake_office_abc123", officeSheetFileParentType},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			runtime, reg := newSheetMediaTestRuntime(t)
+			// UploadDriveMediaAllTyped opens the file via the runtime's FileIO,
+			// which sandboxes paths to the current working directory; chdir to a
+			// temp dir and pass a relative name so the open is allowed.
+			cmdutil.TestChdir(t, t.TempDir())
+			if err := os.WriteFile("img.png", []byte("png-bytes"), 0o600); err != nil {
+				t.Fatal(err)
+			}
+
+			stub := &httpmock.Stub{
+				Method: "POST",
+				URL:    "/open-apis/drive/v1/medias/upload_all",
+				Body: map[string]interface{}{
+					"code": 0,
+					"data": map[string]interface{}{"file_token": "boxTOK123"},
+				},
+			}
+			reg.Register(stub)
+
+			fileToken, err := uploadSheetImage(runtime, tc.token, "img.png", "img.png", 9)
+			if err != nil {
+				t.Fatalf("uploadSheetImage() error: %v", err)
+			}
+			if fileToken != "boxTOK123" {
+				t.Fatalf("file_token = %q, want boxTOK123", fileToken)
+			}
+
+			body := decodeSheetMediaMultipartBody(t, stub)
+			if got := body.Fields["parent_type"]; got != tc.wantParentType {
+				t.Fatalf("parent_type = %q, want %q", got, tc.wantParentType)
+			}
+			if got := body.Fields["parent_node"]; got != tc.token {
+				t.Fatalf("parent_node = %q, want %q", got, tc.token)
+			}
+			if got := body.Fields["file_name"]; got != "img.png" {
+				t.Fatalf("file_name = %q, want img.png", got)
+			}
+		})
+	}
+}
+
+// TestUploadSheetImage_FileOpenError confirms a missing image surfaces as a
+// typed validation error (category=validation, subtype=invalid_argument) with
+// the original os-level cause preserved for errors.Is, and proves the upload
+// endpoint is never hit. No httpmock stub is registered, so if uploadSheetImage
+// ever tried to POST upload_all the RoundTrip would return a
+// "no stub for POST ..." network failure — that would surface as a
+// non-validation category and fail the metadata assertion below. The
+// category=validation + fs.ErrNotExist cause therefore strictly implies the
+// short-circuit happened before the wire.
+func TestUploadSheetImage_FileOpenError(t *testing.T) {
+	runtime, _ := newSheetMediaTestRuntime(t)
+	cmdutil.TestChdir(t, t.TempDir())
+
+	_, err := uploadSheetImage(runtime, "shtcnTOK123", "missing.png", "missing.png", 1)
+	if err == nil {
+		t.Fatal("expected error for missing file, got nil")
+	}
+
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("err = %v; want typed problem carrier", err)
+	}
+	if p.Category != errs.CategoryValidation {
+		t.Fatalf("category = %q, want %q (non-validation implies the upload endpoint was reached)", p.Category, errs.CategoryValidation)
+	}
+	if p.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("subtype = %q, want %q", p.Subtype, errs.SubtypeInvalidArgument)
+	}
+	if !errors.Is(err, fs.ErrNotExist) {
+		t.Fatalf("err = %v; want wrapped fs.ErrNotExist cause to be preserved", err)
+	}
+}
+
+func newSheetMediaTestRuntime(t *testing.T) (*common.RuntimeContext, *httpmock.Registry) {
+	t.Helper()
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cfg := &core.CliConfig{
+		AppID:     "test-sheets-media-" + t.Name(),
+		AppSecret: "test-secret",
+		Brand:     core.BrandFeishu,
+	}
+	f, _, _, reg := cmdutil.TestFactory(t, cfg)
+	runtime := common.TestNewRuntimeContextForAPI(context.Background(), &cobra.Command{Use: "sheets"}, cfg, f, core.AsBot)
+	return runtime, reg
+}
+
+type sheetMediaCapturedMultipart struct {
+	Fields map[string]string
+	Files  map[string][]byte
+}
+
+func decodeSheetMediaMultipartBody(t *testing.T, stub *httpmock.Stub) sheetMediaCapturedMultipart {
+	t.Helper()
+	contentType := stub.CapturedHeaders.Get("Content-Type")
+	mediaType, params, err := mime.ParseMediaType(contentType)
+	if err != nil {
+		t.Fatalf("parse content-type %q: %v", contentType, err)
+	}
+	if mediaType != "multipart/form-data" {
+		t.Fatalf("content type = %q, want multipart/form-data", mediaType)
+	}
+	reader := multipart.NewReader(bytes.NewReader(stub.CapturedBody), params["boundary"])
+	body := sheetMediaCapturedMultipart{Fields: map[string]string{}, Files: map[string][]byte{}}
+	for {
+		part, err := reader.NextPart()
+		if err != nil {
+			if err == io.EOF {
+				break
+			}
+			t.Fatalf("read multipart part: %v", err)
+		}
+		buf := new(bytes.Buffer)
+		if _, err := buf.ReadFrom(part); err != nil {
+			t.Fatalf("read multipart body for %q: %v", part.FormName(), err)
+		}
+		if part.FileName() != "" {
+			body.Files[part.FormName()] = buf.Bytes()
+			continue
+		}
+		body.Fields[part.FormName()] = buf.String()
+	}
+	return body
+}

shortcuts/sheets/sheets_perf_bench_test.go

@@ -0,0 +1,272 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+// These benchmarks back the memory review of the sheets fan-out / download
+// paths. They measure two hot spots:
+//
+//   1. fillCellsMatrix — fan-out shortcuts (+cells-set-style, +dropdown-set,
+//      +cells-batch-set-style, +dropdown-update) expand one A1 range into a
+//      rows×cols matrix of per-cell maps. A tiny input string ("A1:Z100000")
+//      explodes into millions of heap maps with no upper bound.
+//
+//   2. the export-download reader — strings.NewReader(string(rawBody)) copies
+//      the whole downloaded file once more before saving it.
+//
+// Run: go test ./shortcuts/sheets -run XXX -bench 'FillCellsMatrix|DownloadReader' -benchmem
+
+var styleProto = map[string]interface{}{
+	"cell_styles":   map[string]interface{}{"bold": true, "fg_color": "#FF0000"},
+	"border_styles": map[string]interface{}{"top": map[string]interface{}{"style": "solid"}},
+}
+
+func benchFillCellsMatrix(b *testing.B, rows, cols int) {
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		m := fillCellsMatrix(rows, cols, styleProto)
+		if len(m) != rows {
+			b.Fatalf("bad matrix")
+		}
+	}
+}
+
+func BenchmarkFillCellsMatrix_100(b *testing.B)   { benchFillCellsMatrix(b, 10, 10) }     // A1:J10
+func BenchmarkFillCellsMatrix_10K(b *testing.B)   { benchFillCellsMatrix(b, 1000, 10) }   // A1:J1000
+func BenchmarkFillCellsMatrix_100K(b *testing.B)  { benchFillCellsMatrix(b, 10000, 10) }  // A1:J10000
+func BenchmarkFillCellsMatrix_2600K(b *testing.B) { benchFillCellsMatrix(b, 100000, 26) } // A1:Z100000
+
+// TestFanoutMatrixPeakMemory reports the concrete resident-heap delta of
+// materializing a large fan-out matrix, so the review doc can quote real MB.
+// Not an assertion — it prints numbers under `go test -v -run PeakMemory`.
+func TestFanoutMatrixPeakMemory(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping memory probe in -short")
+	}
+	cases := []struct {
+		name       string
+		rows, cols int
+	}{
+		{"A1:Z10000 (260K cells)", 10000, 26},
+		{"A1:Z100000 (2.6M cells)", 100000, 26},
+	}
+	for _, c := range cases {
+		var before, after runtime.MemStats
+		runtime.GC()
+		runtime.ReadMemStats(&before)
+		m := fillCellsMatrix(c.rows, c.cols, styleProto)
+		runtime.ReadMemStats(&after)
+		runtime.KeepAlive(m)
+		t.Logf("%-26s heap +%6.1f MB  (%d total allocs)",
+			c.name,
+			float64(after.HeapAlloc-before.HeapAlloc)/(1024*1024),
+			after.Mallocs-before.Mallocs)
+	}
+}
+
+// --- +table-put / +workbook-create matrix materialization (sibling #1 path) ---
+//
+// buildSheetMatrix turns the caller's --sheets/--values into a rows×cols matrix
+// of per-cell maps, the same unbounded blow-up as fillCellsMatrix but on the
+// table-put ingress (tablePutMaxCellsPerWrite only slices the *write*, not this
+// in-memory build). checkCellBudget rejects oversized payloads before this runs.
+
+func makeTypelessSpec(rows, cols int) *tableSheetSpec {
+	c := make([]tableColumnSpec, cols)
+	r := make([][]interface{}, rows)
+	for i := range r {
+		row := make([]interface{}, cols)
+		for j := range row {
+			row[j] = "x"
+		}
+		r[i] = row
+	}
+	return &tableSheetSpec{Columns: c, Rows: r}
+}
+
+func benchBuildSheetMatrix(b *testing.B, rows, cols int) {
+	spec := makeTypelessSpec(rows, cols)
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		m, err := buildSheetMatrix(spec, true)
+		if err != nil || len(m) != rows+1 {
+			b.Fatalf("bad matrix")
+		}
+	}
+}
+
+func BenchmarkBuildSheetMatrix_100K(b *testing.B)  { benchBuildSheetMatrix(b, 10000, 10) }  // 100K cells
+func BenchmarkBuildSheetMatrix_2600K(b *testing.B) { benchBuildSheetMatrix(b, 100000, 26) } // 2.6M cells
+
+// TestTablePutMatrixPeakMemory reports the resident-heap delta of materializing
+// a large table-put matrix (the cost checkCellBudget now prevents), so the
+// review doc can quote real MB. Not an assertion — prints under -v -run PeakMemory.
+func TestTablePutMatrixPeakMemory(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping memory probe in -short")
+	}
+	for _, c := range []struct {
+		name       string
+		rows, cols int
+	}{
+		{"100000×26 (2.6M cells)", 100000, 26},
+	} {
+		spec := makeTypelessSpec(c.rows, c.cols)
+		var before, after runtime.MemStats
+		runtime.GC()
+		runtime.ReadMemStats(&before)
+		m, _ := buildSheetMatrix(spec, true)
+		runtime.ReadMemStats(&after)
+		runtime.KeepAlive(m)
+		t.Logf("%-24s buildSheetMatrix heap +%6.1f MB  (%d total allocs)",
+			c.name,
+			float64(after.HeapAlloc-before.HeapAlloc)/(1024*1024),
+			after.Mallocs-before.Mallocs)
+	}
+}
+
+// --- export-download reader copy ---
+
+func benchDownloadReader(b *testing.B, size int, useStringCopy bool) {
+	raw := bytes.Repeat([]byte("x"), size)
+	sink := make([]byte, 32*1024)
+	b.ReportAllocs()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		var r io.Reader
+		if useStringCopy {
+			r = strings.NewReader(string(raw)) // current code: extra full-size copy
+		} else {
+			r = bytes.NewReader(raw) // fix: no copy
+		}
+		for {
+			if _, err := r.Read(sink); err != nil {
+				break
+			}
+		}
+	}
+}
+
+// --- fan-out cell-budget cap (fix for the unbounded matrix blow-up) ---
+
+func TestStampMatrixBudgetCap(t *testing.T) {
+	// 199992 cells (7692×26) sits just under the 200000 cap → allowed.
+	if err := checkStampMatrixBudget("range", "A1:Z7692", 7692, 26); err != nil {
+		t.Fatalf("199992 cells should pass, got: %v", err)
+	}
+	// Exactly at the cap → allowed.
+	if err := checkStampMatrixBudget("range", "A1:A200000", 200000, 1); err != nil {
+		t.Fatalf("200000 cells (== cap) should pass, got: %v", err)
+	}
+	// Just over the cap → rejected.
+	if err := checkStampMatrixBudget("range", "A1:A200001", 200001, 1); err == nil {
+		t.Fatal("200001 cells should be rejected")
+	}
+	// The pathological case from the review (2.6M cells) → rejected.
+	if err := checkStampMatrixBudget("ranges", "Sheet1!A1:Z100000", 100000, 26); err == nil {
+		t.Fatal("2.6M-cell fan-out should be rejected")
+	}
+}
+
+// --- sibling cap gaps: +table-put/+workbook-create payload, batch aggregate,
+//     batch-update operation count (follow-up to the single fan-out cap) ---
+
+// TestTablePutCellBudgetCap covers the --sheets/--values materialization cap:
+// buildSheetMatrix builds the whole matrix in memory, so the total cell count is
+// bounded before that allocation, summed across all sheets.
+func TestTablePutCellBudgetCap(t *testing.T) {
+	// 1000×1000 = 1,000,000 == cap → allowed.
+	atCap := &tablePayload{Sheets: []tableSheetSpec{{
+		Columns: make([]tableColumnSpec, 1000),
+		Rows:    make([][]interface{}, 1000),
+	}}}
+	if err := atCap.checkCellBudget(); err != nil {
+		t.Fatalf("1,000,000 cells (== cap) should pass, got: %v", err)
+	}
+	// 1000×1001 = 1,001,000 > cap → rejected.
+	over := &tablePayload{Sheets: []tableSheetSpec{{
+		Columns: make([]tableColumnSpec, 1000),
+		Rows:    make([][]interface{}, 1001),
+	}}}
+	if err := over.checkCellBudget(); err == nil {
+		t.Fatal("1,001,000 cells should be rejected")
+	}
+	// Budget is summed across sheets, not per-sheet: 600k + 600k = 1.2M > cap.
+	twoSheets := &tablePayload{Sheets: []tableSheetSpec{
+		{Columns: make([]tableColumnSpec, 1000), Rows: make([][]interface{}, 600)},
+		{Columns: make([]tableColumnSpec, 1000), Rows: make([][]interface{}, 600)},
+	}}
+	if err := twoSheets.checkCellBudget(); err == nil {
+		t.Fatal("1.2M cells across two sheets should be rejected")
+	}
+}
+
+// TestBatchStampAggregateCap covers the batch fan-out aggregate budget — the
+// per-range cap can't stop many ranges from summing past the matrix ceiling.
+func TestBatchStampAggregateCap(t *testing.T) {
+	if err := checkBatchStampBudget(maxStampMatrixCells); err != nil {
+		t.Fatalf("aggregate == cap should pass, got: %v", err)
+	}
+	if err := checkBatchStampBudget(maxStampMatrixCells + 1); err == nil {
+		t.Fatal("aggregate over cap should be rejected")
+	}
+}
+
+// TestBatchFanoutRangeCountCap drives a fan-out shortcut with > maxBatchRanges
+// ranges and expects the shared validateDropdownRanges cap to reject it.
+func TestBatchFanoutRangeCountCap(t *testing.T) {
+	ranges := make([]string, maxBatchRanges+1)
+	for i := range ranges {
+		ranges[i] = "sheet1!A1"
+	}
+	rangesJSON, _ := json.Marshal(ranges)
+	_, _, err := runShortcutCapturingErr(t, CellsBatchSetStyle, []string{
+		"--url", testURL,
+		"--ranges", string(rangesJSON),
+		"--font-weight", "bold",
+		"--dry-run",
+	})
+	requireValidation(t, err, "at most")
+}
+
+// TestBatchOperationsCountCap covers the +batch-update sub-operation count cap.
+func TestBatchOperationsCountCap(t *testing.T) {
+	ops := make([]interface{}, maxBatchOperations+1)
+	for i := range ops {
+		ops[i] = map[string]interface{}{"shortcut": "+cells-set", "input": map[string]interface{}{}}
+	}
+	_, err := translateBatchOperations(ops, testURL)
+	if err == nil || !strings.Contains(err.Error(), "at most") {
+		t.Fatalf("expected operations count cap error, got: %v", err)
+	}
+}
+
+// BenchmarkStampBudget_RejectsOversized is the "after" side of the fix: the same
+// A1:Z100000 input that BenchmarkFillCellsMatrix_2600K shows costing ~917MB /
+// 5.3M allocs is now rejected up front, allocating only the error string.
+func BenchmarkStampBudget_RejectsOversized(b *testing.B) {
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		if err := checkStampMatrixBudget("range", "A1:Z100000", 100000, 26); err == nil {
+			b.Fatal("expected rejection")
+		}
+	}
+}
+
+func BenchmarkDownloadReader_StringCopy_1MB(b *testing.B)  { benchDownloadReader(b, 1<<20, true) }
+func BenchmarkDownloadReader_BytesNoCopy_1MB(b *testing.B) { benchDownloadReader(b, 1<<20, false) }
+func BenchmarkDownloadReader_StringCopy_16MB(b *testing.B) { benchDownloadReader(b, 16<<20, true) }
+func BenchmarkDownloadReader_BytesNoCopy_16MB(b *testing.B) {
+	benchDownloadReader(b, 16<<20, false)
+}

shortcuts/sheets/shortcuts.go

@@ -105,6 +105,9 @@ func shortcutList() []common.Shortcut {
 		CellsSearch,
 		CellsReplace,
 
+		// lark_sheet_formula_verify
+		FormulaVerify,
+
 		// lark_sheet_write_cells
 		CellsSet,
 		CellsSetStyle,
@@ -148,5 +151,10 @@ func shortcutList() []common.Shortcut {
 		CellsBatchClear,
 		DropdownUpdate,
 		DropdownDelete,
+
+		// lark_sheet_history
+		HistoryList,
+		HistoryRevert,
+		HistoryRevertStatus,
 	}
 }

shortcuts/slides/shortcuts.go

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

shortcuts/slides/slides_create.go

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

shortcuts/slides/slides_create_test.go

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

shortcuts/slides/slides_replace_pages.go

@@ -0,0 +1,426 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"context"
+	"encoding/json"
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// SlidesReplacePages rebuilds multiple pages inside an existing presentation.
+// It deliberately creates the new page before deleting the old one so a create
+// failure cannot remove existing user content. The operation is not atomic.
+const replacePagesInitialRevisionID = -1
+
+var SlidesReplacePages = common.Shortcut{
+	Service:     "slides",
+	Command:     "+replace-pages",
+	Description: "Batch rebuild pages inside an existing Slides presentation (create before old page, then delete old page; not atomic)",
+	Risk:        "write",
+	Scopes:      []string{"slides:presentation:update", "slides:presentation:write_only"},
+	// wiki:node:read is required only when --presentation is a wiki URL.
+	ConditionalScopes: []string{"wiki:node:read"},
+	AuthTypes:         []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides", Required: true},
+		{Name: "pages", Desc: "JSON array of page replacements (each: {slide_id, content}); supports @file or -", Required: true, Input: []string{common.File, common.Stdin}},
+		{Name: "continue-on-error", Type: "bool", Desc: "continue with later pages after a create/delete failure; default false"},
+		{Name: "validate-only", Type: "bool", Desc: "validate input and build the create/delete plan without write calls"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return err
+		}
+		if ref.Kind == "wiki" {
+			if err := runtime.EnsureScopes([]string{"wiki:node:read"}); err != nil {
+				return err
+			}
+		}
+		pages, err := parseReplacePages(runtime.Str("pages"))
+		if err != nil {
+			return err
+		}
+		return validateReplacePagesInput(pages)
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		dry := common.NewDryRunAPI()
+		resolved, err := prepareReplacePages(runtime)
+		if err != nil {
+			return dry.Set("error", err.Error())
+		}
+		appendReplacePagesDryRunCalls(dry, resolved)
+		return dry.
+			Set("xml_presentation_id", resolved.PresentationID).
+			Set("pages_count", len(resolved.Plan)).
+			Set("plan", replacePagesPlanOutput(resolved.Plan)).
+			Set("note", "dry-run built a create/delete plan from slide_id inputs; no Slides presentation get/create/delete calls were executed")
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		resolved, err := prepareReplacePages(runtime)
+		if err != nil {
+			return err
+		}
+		if runtime.Bool("validate-only") {
+			runtime.Out(map[string]interface{}{
+				"xml_presentation_id": resolved.PresentationID,
+				"pages_count":         len(resolved.Plan),
+				"plan":                replacePagesPlanOutput(resolved.Plan),
+				"status":              "validated",
+				"note":                "validate-only checked input and built the create/delete plan; no Slides presentation get/create/delete calls were executed",
+			}, nil)
+			return nil
+		}
+
+		revisionID := replacePagesInitialRevisionID
+		results := make([]replacePageResult, 0, len(resolved.Plan))
+		for i, item := range resolved.Plan {
+			result, err := replaceOnePage(runtime, resolved.PresentationID, item, revisionID)
+			results = append(results, result)
+			if result.RevisionID != nil {
+				revisionID = *result.RevisionID
+			}
+			if err != nil {
+				if runtime.Bool("continue-on-error") {
+					continue
+				}
+				return appendSlidesProgressHint(err, fmt.Sprintf("slides +replace-pages stopped at item %d/%d; %d page(s) completed before failure; old page is kept when create failed", i+1, len(resolved.Plan), countReplacedPages(results)))
+			}
+		}
+
+		out := map[string]interface{}{
+			"xml_presentation_id": resolved.PresentationID,
+			"pages_count":         len(resolved.Plan),
+			"results":             replacePageResultsOutput(results),
+			"status":              "completed",
+			"summary":             replacePagesSummaryOutput(results),
+			"note":                "batch replace is not atomic; each page was created before its old page was deleted",
+		}
+		if revisionID != replacePagesInitialRevisionID {
+			out["revision_id"] = revisionID
+		}
+		if hasReplacePageFailures(results) {
+			out["status"] = "partial_failure"
+			return runtime.OutPartialFailure(out, nil)
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+}
+
+type replacePageInput struct {
+	SlideID string
+	Content string
+}
+
+type replacePagePlanItem struct {
+	OldSlideID string
+	Content    string
+	Locator    string
+}
+
+type replacePagesPrepared struct {
+	PresentationID string
+	Plan           []replacePagePlanItem
+}
+
+type replacePageResult struct {
+	OldSlideID string
+	NewSlideID string
+	Status     string
+	Error      string
+	RevisionID *int
+}
+
+func prepareReplacePages(runtime *common.RuntimeContext) (*replacePagesPrepared, error) {
+	ref, err := parsePresentationRef(runtime.Str("presentation"))
+	if err != nil {
+		return nil, err
+	}
+	presentationID, err := resolvePresentationID(runtime, ref)
+	if err != nil {
+		return nil, err
+	}
+	pages, err := parseReplacePages(runtime.Str("pages"))
+	if err != nil {
+		return nil, err
+	}
+	if err := validateReplacePagesInput(pages); err != nil {
+		return nil, err
+	}
+
+	plan, err := buildReplacePagesPlan(pages)
+	if err != nil {
+		return nil, err
+	}
+	return &replacePagesPrepared{PresentationID: presentationID, Plan: plan}, nil
+}
+
+func parseReplacePages(raw string) ([]replacePageInput, error) {
+	s := strings.TrimSpace(raw)
+	if s == "" {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages cannot be empty").WithParam("--pages")
+	}
+	var decoded []map[string]interface{}
+	if err := json.Unmarshal([]byte(s), &decoded); err != nil {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages invalid JSON, must be an array of objects: %v", err).WithParam("--pages").WithCause(err)
+	}
+	out := make([]replacePageInput, 0, len(decoded))
+	for i, m := range decoded {
+		p := replacePageInput{}
+		if v, ok := m["slide_number"]; ok {
+			_ = v
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].slide_number is no longer supported; use slide_id", i).WithParam("--pages").WithHint("read current slide IDs first, then pass slide_id for each page replacement")
+		}
+		if v, ok := m["slide_id"]; ok {
+			s, ok := v.(string)
+			if !ok {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].slide_id must be a string", i).WithParam("--pages")
+			}
+			p.SlideID = s
+		}
+		if v, ok := m["content"]; ok {
+			s, ok := v.(string)
+			if !ok {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].content must be a string", i).WithParam("--pages")
+			}
+			p.Content = s
+		}
+		out = append(out, p)
+	}
+	return out, nil
+}
+
+func validateReplacePagesInput(pages []replacePageInput) error {
+	if len(pages) == 0 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages must contain at least 1 item").WithParam("--pages")
+	}
+	seenIDs := map[string]bool{}
+	for i, p := range pages {
+		id := strings.TrimSpace(p.SlideID)
+		if id == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].slide_id is required", i).WithParam("--pages")
+		}
+		if seenIDs[id] {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages contains duplicate slide_id %q", id).WithParam("--pages")
+		}
+		seenIDs[id] = true
+		if strings.TrimSpace(p.Content) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].content cannot be empty", i).WithParam("--pages")
+		}
+		if err := validateCompleteSlideXML(p.Content); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--pages[%d].content must be a complete <slide> XML element: %v", i, err).WithParam("--pages").WithCause(err)
+		}
+	}
+	return nil
+}
+
+func validateCompleteSlideXML(content string) error {
+	dec := xml.NewDecoder(strings.NewReader(content))
+	depth := 0
+	seenRoot := false
+	for {
+		tok, err := dec.Token()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			return err
+		}
+		switch t := tok.(type) {
+		case xml.StartElement:
+			if depth == 0 {
+				if seenRoot {
+					return invalidSlideXMLStructureError("multiple root elements")
+				}
+				if t.Name.Local != "slide" {
+					return invalidSlideXMLStructureError("root element is <%s>, want <slide>", t.Name.Local)
+				}
+				seenRoot = true
+			}
+			depth++
+		case xml.EndElement:
+			depth--
+		case xml.CharData:
+			if depth == 0 && strings.TrimSpace(string(t)) != "" {
+				return invalidSlideXMLStructureError("non-whitespace text outside root element")
+			}
+		}
+	}
+	if !seenRoot {
+		return invalidSlideXMLStructureError("missing root element")
+	}
+	if depth != 0 {
+		return invalidSlideXMLStructureError("unclosed XML element")
+	}
+	return nil
+}
+
+func invalidSlideXMLStructureError(format string, args ...interface{}) error {
+	return errs.NewValidationError(errs.SubtypeInvalidArgument, format, args...)
+}
+
+func buildReplacePagesPlan(pages []replacePageInput) ([]replacePagePlanItem, error) {
+	plan := make([]replacePagePlanItem, 0, len(pages))
+	for _, page := range pages {
+		id := strings.TrimSpace(page.SlideID)
+		plan = append(plan, replacePagePlanItem{
+			OldSlideID: id,
+			Content:    page.Content,
+			Locator:    "slide_id",
+		})
+	}
+	return plan, nil
+}
+
+func appendReplacePagesDryRunCalls(dry *common.DryRunAPI, resolved *replacePagesPrepared) {
+	dry.Desc("Batch replace pages in-place: create each new page before old page, then delete old page (not atomic)")
+	for i, item := range resolved.Plan {
+		dry.POST(fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s/slide", validate.EncodePathSegment(resolved.PresentationID))).
+			Desc(fmt.Sprintf("[%d/%d] Create replacement before old slide %s", i*2+1, len(resolved.Plan)*2, item.OldSlideID)).
+			Params(map[string]interface{}{"revision_id": "<latest_or_revision_returned_by_previous_step>"}).
+			Body(map[string]interface{}{
+				"slide":           map[string]interface{}{"content": item.Content},
+				"before_slide_id": item.OldSlideID,
+			})
+		dry.DELETE(fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s/slide", validate.EncodePathSegment(resolved.PresentationID))).
+			Desc(fmt.Sprintf("[%d/%d] Delete old slide %s after create succeeds", i*2+2, len(resolved.Plan)*2, item.OldSlideID)).
+			Params(map[string]interface{}{
+				"slide_id":    item.OldSlideID,
+				"revision_id": "<revision_returned_by_create>",
+			})
+	}
+}
+
+func replaceOnePage(runtime *common.RuntimeContext, presentationID string, item replacePagePlanItem, revisionID int) (replacePageResult, error) {
+	result := replacePageResult{
+		OldSlideID: item.OldSlideID,
+		Status:     "pending",
+	}
+	slideURL := fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s/slide", validate.EncodePathSegment(presentationID))
+	createData, err := runtime.CallAPITyped(
+		"POST",
+		slideURL,
+		map[string]interface{}{"revision_id": revisionID},
+		map[string]interface{}{
+			"slide":           map[string]interface{}{"content": item.Content},
+			"before_slide_id": item.OldSlideID,
+		},
+	)
+	if err != nil {
+		result.Status = "create_failed"
+		result.Error = err.Error()
+		return result, err
+	}
+	newSlideID := common.GetString(createData, "slide_id")
+	if newSlideID == "" {
+		err := errs.NewInternalError(errs.SubtypeInvalidResponse, "slide.create returned no slide_id for replacement of slide_id %q", item.OldSlideID)
+		result.Status = "create_failed"
+		result.Error = err.Error()
+		return result, err
+	}
+	result.NewSlideID = newSlideID
+	if rev, ok := revisionFromData(createData); ok {
+		revisionID = rev
+		result.RevisionID = &rev
+	}
+
+	deleteData, err := runtime.CallAPITyped(
+		"DELETE",
+		slideURL,
+		map[string]interface{}{
+			"slide_id":    item.OldSlideID,
+			"revision_id": revisionID,
+		},
+		nil,
+	)
+	if err != nil {
+		result.Status = "delete_failed"
+		result.Error = err.Error()
+		return result, err
+	}
+	if rev, ok := revisionFromData(deleteData); ok {
+		result.RevisionID = &rev
+	}
+	result.Status = "replaced"
+	return result, nil
+}
+
+func revisionFromData(data map[string]interface{}) (int, bool) {
+	if _, ok := data["revision_id"]; !ok {
+		return 0, false
+	}
+	return int(common.GetFloat(data, "revision_id")), true
+}
+
+func replacePagesPlanOutput(plan []replacePagePlanItem) []map[string]interface{} {
+	out := make([]map[string]interface{}, 0, len(plan))
+	for _, item := range plan {
+		out = append(out, map[string]interface{}{
+			"old_slide_id":           item.OldSlideID,
+			"insert_before_slide_id": item.OldSlideID,
+			"locator":                item.Locator,
+			"action":                 "create_before_then_delete_old",
+		})
+	}
+	return out
+}
+
+func replacePageResultsOutput(results []replacePageResult) []map[string]interface{} {
+	out := make([]map[string]interface{}, 0, len(results))
+	for _, result := range results {
+		m := map[string]interface{}{
+			"old_slide_id": result.OldSlideID,
+			"status":       result.Status,
+		}
+		if result.NewSlideID != "" {
+			m["new_slide_id"] = result.NewSlideID
+		}
+		if result.Error != "" {
+			m["error"] = result.Error
+		}
+		if result.RevisionID != nil {
+			m["revision_id"] = *result.RevisionID
+		}
+		out = append(out, m)
+	}
+	return out
+}
+
+func replacePagesSummaryOutput(results []replacePageResult) map[string]interface{} {
+	replaced := countReplacedPages(results)
+	return map[string]interface{}{
+		"replaced": replaced,
+		"failed":   len(results) - replaced,
+		"total":    len(results),
+	}
+}
+
+func countReplacedPages(results []replacePageResult) int {
+	n := 0
+	for _, result := range results {
+		if result.Status == "replaced" {
+			n++
+		}
+	}
+	return n
+}
+
+func hasReplacePageFailures(results []replacePageResult) bool {
+	for _, result := range results {
+		if result.Status == "create_failed" || result.Status == "delete_failed" {
+			return true
+		}
+	}
+	return false
+}

shortcuts/slides/slides_replace_pages_test.go

@@ -0,0 +1,341 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/internal/output"
+)
+
+func TestReplacePagesDeclaredScopes(t *testing.T) {
+	if got := SlidesReplacePages.ScopesForIdentity("user"); !reflect.DeepEqual(got, []string{"slides:presentation:update", "slides:presentation:write_only"}) {
+		t.Fatalf("user preflight scopes = %#v, want slides update/write_only only", got)
+	}
+	if got := SlidesReplacePages.ScopesForIdentity("bot"); !reflect.DeepEqual(got, []string{"slides:presentation:update", "slides:presentation:write_only"}) {
+		t.Fatalf("bot preflight scopes = %#v, want slides update/write_only only", got)
+	}
+
+	got := SlidesReplacePages.DeclaredScopesForIdentity("user")
+	want := []string{"slides:presentation:update", "slides:presentation:write_only", "wiki:node:read"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("declared scopes = %#v, want %#v", got, want)
+	}
+}
+
+func TestReplacePagesCreatesBeforeThenDeletesOld(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	var requestOrder []string
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"slide_id": "new2", "revision_id": 11},
+		},
+		OnMatch: func(req *http.Request) {
+			requestOrder = append(requestOrder, req.Method)
+		},
+	}
+	reg.Register(createStub)
+	var deleteQuery map[string][]string
+	deleteStub := &httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"revision_id": 12},
+		},
+		OnMatch: func(req *http.Request) {
+			requestOrder = append(requestOrder, req.Method)
+			deleteQuery = req.URL.Query()
+		},
+	}
+	reg.Register(deleteStub)
+
+	pages := `[{"slide_id":"old2","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"}]`
+	err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+		"+replace-pages",
+		"--presentation", "pres_abc",
+		"--pages", pages,
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var createBody struct {
+		Slide struct {
+			Content string `json:"content"`
+		} `json:"slide"`
+		BeforeSlideID string `json:"before_slide_id"`
+	}
+	if err := json.Unmarshal(createStub.CapturedBody, &createBody); err != nil {
+		t.Fatalf("decode create body: %v\nraw=%s", err, createStub.CapturedBody)
+	}
+	if createBody.BeforeSlideID != "old2" {
+		t.Fatalf("before_slide_id = %q, want old2", createBody.BeforeSlideID)
+	}
+	if !strings.Contains(createBody.Slide.Content, "<slide") {
+		t.Fatalf("create content = %q", createBody.Slide.Content)
+	}
+	if !reflect.DeepEqual(requestOrder, []string{"POST", "DELETE"}) {
+		t.Fatalf("request order = %#v, want POST then DELETE", requestOrder)
+	}
+	deleteURL := string(deleteStub.CapturedBody)
+	if deleteURL != "" {
+		t.Fatalf("delete body = %q, want empty", deleteURL)
+	}
+	if got := deleteQuery["slide_id"]; !reflect.DeepEqual(got, []string{"old2"}) {
+		t.Fatalf("delete slide_id = %#v, want old2", got)
+	}
+	if got := deleteQuery["revision_id"]; !reflect.DeepEqual(got, []string{"11"}) {
+		t.Fatalf("delete revision_id = %#v, want 11 from create response", got)
+	}
+
+	data := decodeShortcutData(t, stdout)
+	if data["xml_presentation_id"] != "pres_abc" {
+		t.Fatalf("xml_presentation_id = %v", data["xml_presentation_id"])
+	}
+	if data["revision_id"] != float64(12) {
+		t.Fatalf("revision_id = %v, want 12", data["revision_id"])
+	}
+	summary, _ := data["summary"].(map[string]interface{})
+	if summary["failed"] != float64(0) {
+		t.Fatalf("summary.failed = %v, want 0", summary["failed"])
+	}
+	results, _ := data["results"].([]interface{})
+	if len(results) != 1 {
+		t.Fatalf("results len = %d, want 1", len(results))
+	}
+	first, _ := results[0].(map[string]interface{})
+	if first["old_slide_id"] != "old2" || first["new_slide_id"] != "new2" || first["status"] != "replaced" {
+		t.Fatalf("result = %#v", first)
+	}
+}
+
+func TestReplacePagesContinueOnErrorReturnsPartialFailure(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 3350001,
+			"msg":  "invalid param",
+			"data": map[string]interface{}{},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"slide_id": "new2", "revision_id": 11},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"revision_id": 12},
+		},
+	})
+
+	pages := `[
+		{"slide_id":"old1","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"},
+		{"slide_id":"old2","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"}
+	]`
+	err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+		"+replace-pages",
+		"--presentation", "pres_abc",
+		"--pages", pages,
+		"--continue-on-error",
+		"--as", "user",
+	})
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("err = %T %v, want *output.PartialFailureError", err, err)
+	}
+
+	env := decodeReplacePagesEnvelope(t, stdout)
+	if env.OK {
+		t.Fatalf("stdout ok = true, want false for partial failure")
+	}
+	data := env.Data
+	if data["status"] != "partial_failure" {
+		t.Fatalf("status = %v, want partial_failure", data["status"])
+	}
+	summary, _ := data["summary"].(map[string]interface{})
+	if summary["replaced"] != float64(1) || summary["failed"] != float64(1) || summary["total"] != float64(2) {
+		t.Fatalf("summary = %#v, want replaced=1 failed=1 total=2", summary)
+	}
+	results, _ := data["results"].([]interface{})
+	if len(results) != 2 {
+		t.Fatalf("results len = %d, want 2", len(results))
+	}
+	first, _ := results[0].(map[string]interface{})
+	second, _ := results[1].(map[string]interface{})
+	if first["status"] != "create_failed" {
+		t.Fatalf("first status = %v, want create_failed", first["status"])
+	}
+	if second["status"] != "replaced" || second["new_slide_id"] != "new2" {
+		t.Fatalf("second result = %#v, want replaced with new2", second)
+	}
+}
+
+func TestReplacePagesContinueOnErrorDeleteFailureIncludesNewSlideID(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{"slide_id": "new1", "revision_id": 11},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc/slide",
+		Body: map[string]interface{}{
+			"code": 3350001,
+			"msg":  "invalid param",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	pages := `[{"slide_id":"old1","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"}]`
+	err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+		"+replace-pages",
+		"--presentation", "pres_abc",
+		"--pages", pages,
+		"--continue-on-error",
+		"--as", "user",
+	})
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("err = %T %v, want *output.PartialFailureError", err, err)
+	}
+
+	env := decodeReplacePagesEnvelope(t, stdout)
+	if env.OK {
+		t.Fatalf("stdout ok = true, want false for partial failure")
+	}
+	results, _ := env.Data["results"].([]interface{})
+	if len(results) != 1 {
+		t.Fatalf("results len = %d, want 1", len(results))
+	}
+	first, _ := results[0].(map[string]interface{})
+	if first["status"] != "delete_failed" {
+		t.Fatalf("status = %v, want delete_failed", first["status"])
+	}
+	if first["new_slide_id"] != "new1" {
+		t.Fatalf("new_slide_id = %v, want new1", first["new_slide_id"])
+	}
+}
+
+func TestReplacePagesDryRunPlansOnly(t *testing.T) {
+	t.Parallel()
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+
+	pages := `[{"slide_id":"old2","content":"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"}]`
+	err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+		"+replace-pages",
+		"--presentation", "pres_abc",
+		"--pages", pages,
+		"--dry-run",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var out map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &out); err != nil {
+		t.Fatalf("decode dry-run: %v\nraw=%s", err, stdout.String())
+	}
+	if out["xml_presentation_id"] != "pres_abc" {
+		t.Fatalf("xml_presentation_id = %v", out["xml_presentation_id"])
+	}
+	plan, _ := out["plan"].([]interface{})
+	if len(plan) != 1 {
+		t.Fatalf("plan len = %d, want 1", len(plan))
+	}
+	item, _ := plan[0].(map[string]interface{})
+	if item["old_slide_id"] != "old2" || item["action"] != "create_before_then_delete_old" {
+		t.Fatalf("plan item = %#v", item)
+	}
+	api, _ := out["api"].([]interface{})
+	if len(api) != 2 {
+		t.Fatalf("api len = %d, want create/delete plan", len(api))
+	}
+}
+
+func TestReplacePagesValidationParam(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		pages string
+	}{
+		{"empty pages", `[]`},
+		{"slide number no longer supported", `[{"slide_number":1,"content":"<slide/>"}]`},
+		{"no locator", `[{"content":"<slide/>"}]`},
+		{"empty content", `[{"slide_id":"s1","content":"  "}]`},
+		{"not slide XML", `[{"slide_id":"s1","content":"<shape/>"}]`},
+		{"duplicate id", `[{"slide_id":"s1","content":"<slide/>"},{"slide_id":"s1","content":"<slide/>"}]`},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+			err := runSlidesShortcut(t, f, stdout, SlidesReplacePages, []string{
+				"+replace-pages",
+				"--presentation", "pres_abc",
+				"--pages", tt.pages,
+				"--as", "user",
+			})
+			var ve *errs.ValidationError
+			if !errors.As(err, &ve) {
+				t.Fatalf("err = %v, want *errs.ValidationError", err)
+			}
+			if ve.Param != "--pages" {
+				t.Fatalf("Param = %q, want --pages", ve.Param)
+			}
+		})
+	}
+}
+
+type replacePagesEnvelope struct {
+	OK   bool                   `json:"ok"`
+	Data map[string]interface{} `json:"data"`
+}
+
+func decodeReplacePagesEnvelope(t *testing.T, stdout interface{ Bytes() []byte }) replacePagesEnvelope {
+	t.Helper()
+	var env replacePagesEnvelope
+	if err := json.Unmarshal(stdout.Bytes(), &env); err != nil {
+		t.Fatalf("decode output: %v\nraw=%s", err, string(stdout.Bytes()))
+	}
+	if env.Data == nil {
+		t.Fatalf("missing data: %#v", env)
+	}
+	return env
+}

shortcuts/slides/slides_replace_slide.go

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

shortcuts/slides/slides_replace_slide_test.go

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

shortcuts/slides/slides_screenshot.go

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

shortcuts/slides/slides_screenshot_test.go

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

shortcuts/slides/slides_xml_get.go

@@ -0,0 +1,144 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// SlidesXMLGet fetches the full XML presentation content and writes it to a
+// local file, keeping the terminal output small for large decks.
+var SlidesXMLGet = common.Shortcut{
+	Service:     "slides",
+	Command:     "+xml-get",
+	Description: "Fetch full presentation XML and save it to a local file",
+	Risk:        "read",
+	Scopes:      []string{"slides:presentation:read"},
+	// wiki:node:read is required only when --presentation is a wiki URL.
+	ConditionalScopes: []string{"wiki:node:read"},
+	AuthTypes:         []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides", Required: true},
+		{Name: "output", Desc: "local XML output path; existing file is overwritten", Required: true},
+		{Name: "revision-id", Type: "int", Default: "-1", Desc: "presentation revision_id; -1 means latest"},
+		{Name: "remove-attr-id", Type: "bool", Desc: "remove XML id attributes in the returned content; useful for read-only inspection, not precise block editing"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return err
+		}
+		if ref.Kind == "wiki" {
+			if err := runtime.EnsureScopes([]string{"wiki:node:read"}); err != nil {
+				return err
+			}
+		}
+		if strings.TrimSpace(runtime.Str("output")) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output cannot be empty").WithParam("--output")
+		}
+		if _, err := runtime.ResolveSavePath(runtime.Str("output")); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output invalid: %v", err).WithParam("--output").WithCause(err)
+		}
+		if runtime.Int("revision-id") < -1 {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--revision-id must be -1 or a non-negative integer").WithParam("--revision-id")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		presentationID := ref.Token
+		dry := common.NewDryRunAPI()
+		if ref.Kind == "wiki" {
+			presentationID = "<resolved_slides_token>"
+			dry.Desc("2-step orchestration: resolve wiki → fetch full presentation XML").
+				GET("/open-apis/wiki/v2/spaces/get_node").
+				Desc("[1] Resolve wiki node to slides presentation").
+				Params(map[string]interface{}{"token": ref.Token})
+		} else {
+			dry.Desc("Fetch full presentation XML and save it to a local file")
+		}
+		params := map[string]interface{}{
+			"revision_id": runtime.Int("revision-id"),
+		}
+		if runtime.Bool("remove-attr-id") {
+			params["remove_attr_id"] = true
+		}
+		dry.GET(fmt.Sprintf(
+			"/open-apis/slides_ai/v1/xml_presentations/%s",
+			validate.EncodePathSegment(presentationID),
+		)).
+			Params(params)
+		return dry.Set("output", runtime.Str("output")).Set("stdout_content", "suppressed; XML content is saved to --output during execution")
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, err := parsePresentationRef(runtime.Str("presentation"))
+		if err != nil {
+			return err
+		}
+		presentationID, err := resolvePresentationID(runtime, ref)
+		if err != nil {
+			return err
+		}
+
+		params := map[string]interface{}{
+			"revision_id": runtime.Int("revision-id"),
+		}
+		if runtime.Bool("remove-attr-id") {
+			params["remove_attr_id"] = true
+		}
+		data, err := runtime.CallAPITyped(
+			"GET",
+			fmt.Sprintf("/open-apis/slides_ai/v1/xml_presentations/%s", validate.EncodePathSegment(presentationID)),
+			params,
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+
+		presentation := common.GetMap(data, "xml_presentation")
+		content := common.GetString(presentation, "content")
+		if content == "" {
+			return errs.NewInternalError(errs.SubtypeInvalidResponse, "slides xml get returned empty xml_presentation.content")
+		}
+		outputPath := runtime.Str("output")
+		result, err := runtime.FileIO().Save(outputPath, fileio.SaveOptions{
+			ContentType:   "application/xml",
+			ContentLength: int64(len(content)),
+		}, bytes.NewReader([]byte(content)))
+		if err != nil {
+			return common.WrapSaveErrorTyped(err)
+		}
+		resolvedPath, err := runtime.ResolveSavePath(outputPath)
+		if err != nil {
+			return errs.NewInternalError(errs.SubtypeFileIO, "resolve saved XML path %s: %v", outputPath, err).WithCause(err)
+		}
+
+		out := map[string]interface{}{
+			"xml_presentation_id": presentationID,
+			"path":                resolvedPath,
+			"size":                result.Size(),
+			"content_saved":       true,
+		}
+		if revisionID := common.GetFloat(presentation, "revision_id"); revisionID > 0 {
+			out["revision_id"] = int(revisionID)
+		}
+		if runtime.Bool("remove-attr-id") {
+			out["remove_attr_id"] = true
+		}
+		runtime.Out(out, nil)
+		return nil
+	},
+}

shortcuts/slides/slides_xml_get_test.go

@@ -0,0 +1,165 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package slides
+
+import (
+	"errors"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestSlidesXMLGetWritesContentToFileAndSuppressesXML(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	xml := `<presentation><slide id="s1"><shape id="a">hello</shape></slide></presentation>`
+	var capturedQuery url.Values
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_abc",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"xml_presentation": map[string]interface{}{
+					"presentation_id": "pres_abc",
+					"revision_id":     7,
+					"content":         xml,
+				},
+			},
+		},
+		OnMatch: func(req *http.Request) {
+			capturedQuery = req.URL.Query()
+		},
+	})
+
+	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
+		"+xml-get",
+		"--presentation", "pres_abc",
+		"--output", "readback.xml",
+		"--revision-id", "7",
+		"--remove-attr-id",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	path := filepath.Join(dir, "readback.xml")
+	got, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read saved XML: %v", err)
+	}
+	if string(got) != xml {
+		t.Fatalf("saved XML = %q, want %q", got, xml)
+	}
+	if strings.Contains(stdout.String(), xml) {
+		t.Fatalf("stdout leaked full XML content: %s", stdout.String())
+	}
+	if got := capturedQuery.Get("revision_id"); got != "7" {
+		t.Fatalf("revision_id query = %q, want 7", got)
+	}
+	if got := capturedQuery.Get("remove_attr_id"); got != "true" {
+		t.Fatalf("remove_attr_id query = %q, want true", got)
+	}
+
+	data := decodeShortcutData(t, stdout)
+	if data["xml_presentation_id"] != "pres_abc" {
+		t.Fatalf("xml_presentation_id = %v, want pres_abc", data["xml_presentation_id"])
+	}
+	if data["revision_id"] != float64(7) {
+		t.Fatalf("revision_id = %v, want 7", data["revision_id"])
+	}
+	if data["size"] != float64(len(xml)) {
+		t.Fatalf("size = %v, want %d", data["size"], len(xml))
+	}
+	gotPath, _ := data["path"].(string)
+	if !filepath.IsAbs(gotPath) {
+		t.Fatalf("path = %v, want absolute path", gotPath)
+	}
+	if !strings.HasSuffix(gotPath, "readback.xml") {
+		t.Fatalf("path = %v, want readback.xml suffix", gotPath)
+	}
+}
+
+func TestSlidesXMLGetResolvesWikiPresentation(t *testing.T) {
+	dir := t.TempDir()
+	withSlidesTestWorkingDir(t, dir)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"obj_type":  "slides",
+					"obj_token": "pres_real",
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/slides_ai/v1/xml_presentations/pres_real",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"xml_presentation": map[string]interface{}{
+					"content": `<presentation/>`,
+				},
+			},
+		},
+	})
+
+	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
+		"+xml-get",
+		"--presentation", "https://example.feishu.cn/wiki/wikcn123",
+		"--output", "wiki.xml",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	data := decodeShortcutData(t, stdout)
+	if data["xml_presentation_id"] != "pres_real" {
+		t.Fatalf("xml_presentation_id = %v, want pres_real", data["xml_presentation_id"])
+	}
+}
+
+func TestSlidesXMLGetRejectsUnsafeOutputPath(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+	err := runSlidesShortcut(t, f, stdout, SlidesXMLGet, []string{
+		"+xml-get",
+		"--presentation", "pres_abc",
+		"--output", "../readback.xml",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected unsafe output path error, got nil")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T %v", err, err)
+	}
+	if problem.Category != errs.CategoryValidation {
+		t.Fatalf("category = %q, want %q", problem.Category, errs.CategoryValidation)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T %v", err, err)
+	}
+	if validationErr.Param != "--output" {
+		t.Fatalf("param = %q, want --output", validationErr.Param)
+	}
+}

shortcuts/vc/shortcuts.go

@@ -11,6 +11,7 @@ func Shortcuts() []common.Shortcut {
 		VCSearch,
 		VCNotes,
 		VCRecording,
+		VCDetail,
 		VCMeetingJoin,
 		VCMeetingLeave,
 		VCMeetingListActive,

shortcuts/vc/vc_detail.go

@@ -0,0 +1,216 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// vc +detail — get meeting details including note_id and minute_token
+
+package vc
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const detailLogPrefix = "[vc +detail]"
+
+var scopesDetailMeetingIDs = []string{
+	"vc:meeting.meetingevent:read",
+	"vc:record:readonly",
+}
+
+// meetingDetailItem represents a single meeting detail result.
+type meetingDetailItem struct {
+	MeetingID   string `json:"meeting_id"`
+	MeetingNo   string `json:"meeting_no,omitempty"`
+	Topic       string `json:"topic"`
+	StartTime   string `json:"start_time,omitempty"`
+	EndTime     string `json:"end_time,omitempty"`
+	NoteID      string `json:"note_id,omitempty"`
+	MinuteToken string `json:"minute_token,omitempty"`
+	Error       string `json:"error,omitempty"`
+	Hint        string `json:"hint,omitempty"`
+}
+
+// fetchMeetingDetail queries meeting.get and recording API to return a
+// consolidated view of meeting metadata, note_id, and minute_token.
+// Error is only set when an API call actually fails; note_id and minute_token
+// are always present (empty string when not available).
+func fetchMeetingDetail(ctx context.Context, runtime *common.RuntimeContext, meetingID string) *meetingDetailItem {
+	result := &meetingDetailItem{MeetingID: meetingID}
+
+	// Step 1: query meeting detail
+	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)
+	if err != nil {
+		result.Error = fmt.Sprintf("failed to query meeting detail: %v", err)
+		return result
+	}
+
+	meeting, _ := data["meeting"].(map[string]any)
+	if meeting == nil {
+		result.Error = "meeting not found in response"
+		return result
+	}
+
+	if v, ok := meeting["meeting_no"].(string); ok {
+		result.MeetingNo = v
+	}
+	if v, ok := meeting["topic"].(string); ok {
+		result.Topic = v
+	}
+	if v := common.FormatTime(meeting["start_time"]); v != "" {
+		result.StartTime = v
+	}
+	if v := common.FormatTime(meeting["end_time"]); v != "" {
+		result.EndTime = v
+	}
+	if v, ok := meeting["note_id"].(string); ok && v != "" {
+		result.NoteID = v
+	}
+
+	// Step 2: query minute_token via recording API
+	minuteToken, minuteHint, minuteErr := fetchMeetingMinuteToken(runtime, meetingID)
+	if minuteErr != nil {
+		// Recording API failed — surface the error but keep data from step 1
+		result.Error = fmt.Sprintf("failed to query minutes: %v", minuteErr)
+		minuteHint = ""
+	}
+	if minuteToken != "" {
+		result.MinuteToken = minuteToken
+	}
+
+	// Add hints for empty resources (not errors, just informational)
+	var emptyFields []string
+	if result.NoteID == "" {
+		emptyFields = append(emptyFields, "note_id")
+	}
+	if result.MinuteToken == "" && minuteErr == nil && minuteHint == "" {
+		emptyFields = append(emptyFields, "minute_token")
+	}
+	if len(emptyFields) > 0 {
+		result.Hint = fmt.Sprintf("%s not found for this meeting", strings.Join(emptyFields, ", "))
+	}
+	if minuteHint != "" {
+		if result.Hint != "" {
+			result.Hint += "; " + minuteHint
+		} else {
+			result.Hint = minuteHint
+		}
+	}
+
+	return result
+}
+
+// VCDetail gets meeting details including note_id and minute_token.
+var VCDetail = common.Shortcut{
+	Service:     "vc",
+	Command:     "+detail",
+	Description: "Get meeting details including note_id and minute_token by meeting IDs",
+	Risk:        "read",
+	Scopes:      []string{"vc:meeting.meetingevent:read", "vc:record:readonly"},
+	AuthTypes:   []string{"user"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "meeting-ids", Desc: "meeting IDs, comma-separated for batch", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ids := common.SplitCSV(runtime.Str("meeting-ids"))
+		const maxBatchSize = 50
+		if len(ids) > maxBatchSize {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--meeting-ids: too many IDs (%d), maximum is %d", len(ids), maxBatchSize).WithParam("--meeting-ids")
+		}
+		// dynamic scope check
+		result, err := runtime.Factory.Credential.ResolveToken(ctx, credential.NewTokenSpec(runtime.As(), runtime.Config.AppID))
+		if err == nil && result != nil && result.Scopes != "" {
+			if missing := auth.MissingScopes(result.Scopes, scopesDetailMeetingIDs); 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 nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ids := runtime.Str("meeting-ids")
+		return common.NewDryRunAPI().
+			GET("/open-apis/vc/v1/meetings/{meeting_id}").
+			GET("/open-apis/vc/v1/meetings/{meeting_id}/recording").
+			Set("meeting_ids", common.SplitCSV(ids)).
+			Set("steps", "meeting.get → note_id + recording API → minute_token")
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		errOut := runtime.IO().ErrOut
+		meetingIDs := common.SplitCSV(runtime.Str("meeting-ids"))
+		results := make([]*meetingDetailItem, 0, len(meetingIDs))
+
+		const batchDelay = 100 * time.Millisecond
+		fmt.Fprintf(errOut, "%s querying %d meeting_id(s)\n", detailLogPrefix, len(meetingIDs))
+		for i, id := range meetingIDs {
+			if err := ctx.Err(); err != nil {
+				return err
+			}
+			if i > 0 {
+				time.Sleep(batchDelay)
+			}
+			fmt.Fprintf(errOut, "%s querying meeting_id=%s ...\n", detailLogPrefix, sanitizeLogValue(id))
+			results = append(results, fetchMeetingDetail(ctx, runtime, id))
+		}
+
+		successCount := 0
+		for _, r := range results {
+			if r.Error == "" {
+				successCount++
+			}
+		}
+		fmt.Fprintf(errOut, "%s done: %d total, %d succeeded, %d failed\n", detailLogPrefix, len(results), successCount, len(results)-successCount)
+
+		if successCount == 0 && len(results) > 0 {
+			return runtime.OutPartialFailure(map[string]any{"meetings": results}, &output.Meta{Count: len(results)})
+		}
+
+		outData := map[string]any{"meetings": results}
+		runtime.OutFormat(outData, &output.Meta{Count: len(results)}, func(w io.Writer) {
+			if len(results) == 0 {
+				fmt.Fprintln(w, "No meetings.")
+				return
+			}
+			var rows []map[string]interface{}
+			for _, r := range results {
+				row := map[string]interface{}{"meeting_id": r.MeetingID}
+				if r.Error != "" {
+					row["status"] = "FAIL"
+					row["error"] = r.Error
+				} else {
+					row["status"] = "OK"
+				}
+				if r.NoteID != "" {
+					row["note_id"] = r.NoteID
+				}
+				if r.MinuteToken != "" {
+					row["minute_token"] = r.MinuteToken
+				}
+				row["topic"] = r.Topic
+				if r.Hint != "" {
+					row["hint"] = r.Hint
+				}
+				rows = append(rows, row)
+			}
+			output.PrintTable(w, rows)
+			fmt.Fprintf(w, "\n%d meeting(s), %d succeeded, %d failed\n", len(results), successCount, len(results)-successCount)
+		})
+		return nil
+	},
+}

shortcuts/vc/vc_detail_test.go

@@ -0,0 +1,282 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// ---------------------------------------------------------------------------
+// Validation tests
+// ---------------------------------------------------------------------------
+
+func TestDetail_Validation_MissingMeetingIDs(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected validation error for missing --meeting-ids")
+	}
+	if !strings.Contains(err.Error(), "meeting-ids") {
+		t.Errorf("unexpected error message: %v", err)
+	}
+}
+
+func TestDetail_Validation_BatchLimit(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, VCDetail, []string{"+detail", "--meeting-ids", strings.Join(ids, ","), "--as", "user"}, f, nil)
+	if err == nil {
+		t.Fatal("expected batch limit error")
+	}
+	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("Subtype = %q, want SubtypeInvalidArgument", ve.Subtype)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// DryRun tests
+// ---------------------------------------------------------------------------
+
+func TestDetail_DryRun(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--meeting-ids", "m001", "--dry-run", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "/open-apis/vc/v1/meetings/") {
+		t.Errorf("dry-run should show meeting API path, got: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), "recording") {
+		t.Errorf("dry-run should show recording API path, got: %s", stdout.String())
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Execute tests with mocked HTTP
+// ---------------------------------------------------------------------------
+
+func TestDetail_Execute_Success(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingGetStub("m_detail1", "note_001"))
+	reg.Register(recordingOKStub("m_detail1", "https://meetings.feishu.cn/minutes/obc_detail1"))
+
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--meeting-ids", "m_detail1", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meetings, _ := data["meetings"].([]any)
+	if len(meetings) != 1 {
+		t.Fatalf("expected 1 meeting, got %d", len(meetings))
+	}
+	m, _ := meetings[0].(map[string]any)
+	if m["meeting_id"] != "m_detail1" {
+		t.Errorf("meeting_id = %v, want m_detail1", m["meeting_id"])
+	}
+	if m["note_id"] != "note_001" {
+		t.Errorf("note_id = %v, want note_001", m["note_id"])
+	}
+	if m["minute_token"] != "obc_detail1" {
+		t.Errorf("minute_token = %v, want obc_detail1", m["minute_token"])
+	}
+}
+
+func TestDetail_Execute_NoNoteNoMinute(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingGetStub("m_nonote", ""))
+	reg.Register(recordingErrStub("m_nonote", 121004, "not found"))
+
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--meeting-ids", "m_nonote", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Verify hint is present for empty note_id and missing recording
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meetings, _ := data["meetings"].([]any)
+	m, _ := meetings[0].(map[string]any)
+	if hint, _ := m["hint"].(string); !strings.Contains(hint, "note_id") || !strings.Contains(hint, "no minute file for this meeting") {
+		t.Errorf("hint should mention note_id and minute file missing, got: %v", hint)
+	}
+	if errMsg, _ := m["error"].(string); errMsg != "" {
+		t.Errorf("error should be empty, got: %v", errMsg)
+	}
+}
+
+func TestDetail_Execute_MeetingNotFound(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/vc/v1/meetings/m_bad",
+		Body:   map[string]interface{}{"code": 121004, "msg": "data not found"},
+	})
+
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--meeting-ids", "m_bad", "--as", "user"}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+}
+
+func TestDetail_Execute_Batch(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	// m1 succeeds with note and minute
+	reg.Register(meetingGetStub("m_batch1", "note_b1"))
+	reg.Register(recordingOKStub("m_batch1", "https://meetings.feishu.cn/minutes/obc_b1"))
+	// m2 has no note_id but has minute
+	reg.Register(meetingGetStub("m_batch2", ""))
+	reg.Register(recordingOKStub("m_batch2", "https://meetings.feishu.cn/minutes/obc_b2"))
+
+	err := mountAndRun(t, VCDetail, []string{"+detail", "--meeting-ids", "m_batch1,m_batch2", "--as", "user"}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meetings, _ := data["meetings"].([]any)
+	if len(meetings) != 2 {
+		t.Fatalf("expected 2 meetings, got %d", len(meetings))
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Pure function tests
+// ---------------------------------------------------------------------------
+
+func TestFetchMeetingDetail_MeetingWithNoteAndMinute(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingGetStub("m_fn", "note_fn"))
+	reg.Register(recordingOKStub("m_fn", "https://meetings.feishu.cn/minutes/obc_fn"))
+
+	if err := botExec(t, "detail-fn", f, func(_ context.Context, rctx *common.RuntimeContext) error {
+		result := fetchMeetingDetail(context.Background(), rctx, "m_fn")
+		if result.MeetingID != "m_fn" {
+			t.Errorf("meeting_id = %v, want m_fn", result.MeetingID)
+		}
+		if result.NoteID != "note_fn" {
+			t.Errorf("note_id = %v, want note_fn", result.NoteID)
+		}
+		if result.MinuteToken != "obc_fn" {
+			t.Errorf("minute_token = %v, want obc_fn", result.MinuteToken)
+		}
+		if result.Error != "" {
+			t.Errorf("unexpected error: %v", result.Error)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestFetchMeetingDetail_MeetingNotFound(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/vc/v1/meetings/m_nf",
+		Body:   map[string]interface{}{"code": 121004, "msg": "data not found"},
+	})
+
+	if err := botExec(t, "detail-nf", f, func(_ context.Context, rctx *common.RuntimeContext) error {
+		result := fetchMeetingDetail(context.Background(), rctx, "m_nf")
+		if result.Error == "" {
+			t.Error("expected error for meeting not found")
+		}
+		// note_id and minute_token should still be present (empty)
+		if result.NoteID != "" {
+			t.Errorf("note_id = %q, want empty", result.NoteID)
+		}
+		if result.MinuteToken != "" {
+			t.Errorf("minute_token = %q, want empty", result.MinuteToken)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestFetchMeetingDetail_RecordingFailsButNoteOK(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingGetStub("m_partial", "note_partial"))
+	reg.Register(recordingErrStub("m_partial", 121004, "not found"))
+
+	if err := botExec(t, "detail-partial", f, func(_ context.Context, rctx *common.RuntimeContext) error {
+		result := fetchMeetingDetail(context.Background(), rctx, "m_partial")
+		if result.NoteID != "note_partial" {
+			t.Errorf("note_id = %v, want note_partial", result.NoteID)
+		}
+		if result.MinuteToken != "" {
+			t.Errorf("minute_token = %q, want empty", result.MinuteToken)
+		}
+		if result.Error != "" {
+			t.Errorf("error = %q, want empty", result.Error)
+		}
+		if !strings.Contains(result.Hint, "no minute file for this meeting") {
+			t.Errorf("hint = %q, want contains 'no minute file for this meeting'", result.Hint)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestFetchMeetingDetail_RecordingAPIErrorButNoteOK(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingGetStub("m_api_err", "note_apierr"))
+	reg.Register(recordingErrStub("m_api_err", 99999, "weird API error"))
+
+	if err := botExec(t, "detail-apierr", f, func(_ context.Context, rctx *common.RuntimeContext) error {
+		result := fetchMeetingDetail(context.Background(), rctx, "m_api_err")
+		if result.NoteID != "note_apierr" {
+			t.Errorf("note_id = %v, want note_apierr", result.NoteID)
+		}
+		if result.MinuteToken != "" {
+			t.Errorf("minute_token = %q, want empty", result.MinuteToken)
+		}
+		if !strings.Contains(result.Error, "failed to query minutes") || !strings.Contains(result.Error, "weird API error") {
+			t.Errorf("error = %q, want contains 'failed to query minutes' and 'weird API error'", result.Error)
+		}
+		if strings.Contains(result.Hint, "minute_token") {
+			t.Errorf("hint = %q, should not mention minute_token when there is an error", result.Hint)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}

shortcuts/vc/vc_meeting_events_test.go

@@ -838,7 +838,7 @@ func TestVCShortcuts_RegistersMeetingAgentCommands(t *testing.T) {
 	for _, shortcut := range got {
 		commands = append(commands, shortcut.Command)
 	}
-	want := []string{"+search", "+notes", "+recording", "+meeting-join", "+meeting-leave", "+meeting-list-active", "+meeting-events"}
+	want := []string{"+search", "+notes", "+recording", "+detail", "+meeting-join", "+meeting-leave", "+meeting-list-active", "+meeting-events"}
 	if !reflect.DeepEqual(commands, want) {
 		t.Fatalf("shortcut commands = %#v, want %#v", commands, want)
 	}

shortcuts/vc/vc_notes.go

@@ -263,42 +263,35 @@ func asStringSlice(v any) []string {
 }
 
 // fetchMeetingMinuteToken queries the recording API of a meeting and returns
-// the associated minute_token (parsed from the recording URL) and an
-// optional human-friendly error message. On success token is non-empty and
-// errMsg is empty; on failure token is empty and errMsg describes the cause:
-//   - 121004: meeting has no minute file
-//   - 121005: caller has no permission for the meeting recording
-//   - 124002: recording / minute file is still being generated
-//
-// 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,
+// the associated minute_token (parsed from the recording URL), an optional
+// hint for expected missing states, and an error for unexpected failures.
+func fetchMeetingMinuteToken(runtime *common.RuntimeContext, meetingID string) (token, hint string, err error) {
+	data, apiErr := runtime.CallAPITyped(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 {
+	if apiErr != nil {
+		if p, ok := errs.ProblemOf(apiErr); ok {
 			switch p.Code {
 			case recordingNotFoundCode:
-				return "", "no minute file for this meeting"
+				return "", "no minute file for this meeting", nil
 			case recordingNoPermissionCode:
-				return "", "no permission to access this meeting's minute; ask the meeting owner to share the minute"
+				return "", "no permission to access this meeting's minute; ask the meeting owner to share the minute", nil
 			case recordingGeneratingCode:
-				return "", "minute file is still being generated; please retry later"
+				return "", "minute file is still being generated; please retry later", nil
 			}
 		}
-		return "", fmt.Sprintf("failed to query recording: %v", err)
+		return "", "", apiErr
 	}
 
 	recording, _ := data["recording"].(map[string]any)
 	if recording == nil {
-		return "", "no recording available for this meeting"
+		return "", "no recording available for this meeting", nil
 	}
 	recordingURL, _ := recording["url"].(string)
 	if t := extractMinuteToken(recordingURL); t != "" {
-		return t, ""
+		return t, "", nil
 	}
-	return "", "no minute_token found in recording URL"
+	return "", "no minute_token found in recording URL", nil
 }
 
 // fetchNoteByMeetingID queries notes via meeting_id and additionally fetches
@@ -321,7 +314,7 @@ func fetchNoteByMeetingID(ctx context.Context, runtime *common.RuntimeContext, m
 	// Always attempt to query the meeting's minute_token via the recording API,
 	// regardless of whether the meeting has a note_id, so callers always see
 	// minute state for follow-up calls (e.g. `vc +notes --minute-tokens=...`).
-	minuteToken, minuteErr := fetchMeetingMinuteToken(runtime, meetingID)
+	minuteToken, minuteHint, minuteErr := fetchMeetingMinuteToken(runtime, meetingID)
 
 	var result map[string]any
 	var noteErr string
@@ -340,7 +333,13 @@ func fetchNoteByMeetingID(ctx context.Context, runtime *common.RuntimeContext, m
 	if minuteToken != "" {
 		result["minute_token"] = minuteToken
 	}
-	if combined := joinErrors(noteErr, minuteErr); combined != "" {
+	var minuteErrMsg string
+	if minuteHint != "" {
+		minuteErrMsg = minuteHint
+	} else if minuteErr != nil {
+		minuteErrMsg = minuteErr.Error()
+	}
+	if combined := joinErrors(noteErr, minuteErrMsg); combined != "" {
 		result["error"] = combined
 	}
 	return result
@@ -538,6 +537,7 @@ var VCNotes = common.Shortcut{
 	Risk:        "read",
 	Scopes:      []string{"vc:note:read"}, // minimum scope; additional per-flag scopes checked in Validate
 	AuthTypes:   []string{"user"},
+	Hidden:      true, // hidden from --help; prefer vc +detail, minutes +detail, or note +detail
 	HasFormat:   true,
 	Flags: []common.Flag{
 		{Name: "meeting-ids", Desc: "meeting IDs, comma-separated for batch"},

shortcuts/vc/vc_notes_test.go

@@ -792,12 +792,15 @@ func TestFetchMeetingMinuteToken_Success(t *testing.T) {
 	reg.Register(recordingOKStub("m_ok", "https://meetings.feishu.cn/minutes/obctoken_ok"))
 
 	if err := botExec(t, "fmmt-ok", f, func(_ context.Context, rctx *common.RuntimeContext) error {
-		token, msg := fetchMeetingMinuteToken(rctx, "m_ok")
+		token, hint, err := fetchMeetingMinuteToken(rctx, "m_ok")
 		if token != "obctoken_ok" {
 			t.Errorf("token = %q, want obctoken_ok", token)
 		}
-		if msg != "" {
-			t.Errorf("errMsg = %q, want empty", msg)
+		if hint != "" {
+			t.Errorf("hint = %q, want empty", hint)
+		}
+		if err != nil {
+			t.Errorf("err = %v, want nil", err)
 		}
 		return nil
 	}); err != nil {
@@ -823,12 +826,15 @@ func TestFetchMeetingMinuteToken_KnownErrorCodes(t *testing.T) {
 			reg.Register(recordingErrStub(tt.meetingID, tt.code, "err"))
 
 			if err := botExec(t, "fmmt-"+tt.meetingID, f, func(_ context.Context, rctx *common.RuntimeContext) error {
-				token, msg := fetchMeetingMinuteToken(rctx, tt.meetingID)
+				token, hint, err := fetchMeetingMinuteToken(rctx, tt.meetingID)
 				if token != "" {
 					t.Errorf("token = %q, want empty on error", token)
 				}
-				if !strings.Contains(msg, tt.wantMsg) {
-					t.Errorf("errMsg = %q, want contains %q", msg, tt.wantMsg)
+				if !strings.Contains(hint, tt.wantMsg) {
+					t.Errorf("hint = %q, want contains %q", hint, tt.wantMsg)
+				}
+				if err != nil {
+					t.Errorf("err = %v, want nil", err)
 				}
 				return nil
 			}); err != nil {
@@ -844,12 +850,15 @@ func TestFetchMeetingMinuteToken_GenericAPIError(t *testing.T) {
 	reg.Register(recordingErrStub("m_other", 99999, "weird"))
 
 	if err := botExec(t, "fmmt-generic", f, func(_ context.Context, rctx *common.RuntimeContext) error {
-		token, msg := fetchMeetingMinuteToken(rctx, "m_other")
+		token, hint, err := fetchMeetingMinuteToken(rctx, "m_other")
 		if token != "" {
 			t.Errorf("token = %q, want empty", token)
 		}
-		if !strings.Contains(msg, "failed to query recording") {
-			t.Errorf("errMsg = %q, want contains 'failed to query recording'", msg)
+		if hint != "" {
+			t.Errorf("hint = %q, want empty", hint)
+		}
+		if err == nil || !strings.Contains(err.Error(), "weird") {
+			t.Errorf("err = %v, want contains 'weird'", err)
 		}
 		return nil
 	}); err != nil {
@@ -866,12 +875,15 @@ func TestFetchMeetingMinuteToken_NoRecording(t *testing.T) {
 	}))
 
 	if err := botExec(t, "fmmt-norec", f, func(_ context.Context, rctx *common.RuntimeContext) error {
-		token, msg := fetchMeetingMinuteToken(rctx, "m_norec")
+		token, hint, err := fetchMeetingMinuteToken(rctx, "m_norec")
 		if token != "" {
 			t.Errorf("token = %q, want empty", token)
 		}
-		if !strings.Contains(msg, "no recording available") {
-			t.Errorf("errMsg = %q, want contains 'no recording available'", msg)
+		if err != nil {
+			t.Errorf("err = %v, want nil", err)
+		}
+		if !strings.Contains(hint, "no recording available") {
+			t.Errorf("hint = %q, want contains 'no recording available'", hint)
 		}
 		return nil
 	}); err != nil {
@@ -885,12 +897,15 @@ func TestFetchMeetingMinuteToken_URLWithoutToken(t *testing.T) {
 	reg.Register(recordingOKStub("m_notok", "https://example.com/no/minute/path"))
 
 	if err := botExec(t, "fmmt-notok", f, func(_ context.Context, rctx *common.RuntimeContext) error {
-		token, msg := fetchMeetingMinuteToken(rctx, "m_notok")
+		token, hint, err := fetchMeetingMinuteToken(rctx, "m_notok")
 		if token != "" {
 			t.Errorf("token = %q, want empty", token)
 		}
-		if !strings.Contains(msg, "no minute_token found") {
-			t.Errorf("errMsg = %q, want contains 'no minute_token found'", msg)
+		if err != nil {
+			t.Errorf("err = %v, want nil", err)
+		}
+		if !strings.Contains(hint, "no minute_token found") {
+			t.Errorf("hint = %q, want contains 'no minute_token found'", hint)
 		}
 		return nil
 	}); err != nil {
@@ -983,7 +998,7 @@ func TestNotes_MeetingPath_OnlyMinuteFails_PartialSuccess(t *testing.T) {
 		t.Errorf("note_doc_token = %v, want doc_main", got)
 	}
 	assertNoteFieldAbsent(t, note, "minute_token")
-	assertNoteError(t, note, "no permission to access this meeting's minute")
+	assertNoteError(t, note, "no permission to access this meeting's minute; ask the meeting owner to share the minute")
 }
 
 func TestNotes_MeetingPath_NoNote_ButMinuteOK(t *testing.T) {
@@ -1068,6 +1083,7 @@ func TestNotes_MeetingPath_NoteNoPermission_FriendlyHint(t *testing.T) {
 	assertNoteError(t, note,
 		"[121005]",
 		"no read permission for this meeting note",
+		"no permission to access this meeting's minute",
 		"; ", // note + minute causes joined with semicolon
 	)
 }

shortcuts/vc/vc_search.go

@@ -230,9 +230,16 @@ var VCSearch = common.Shortcut{
 			data = map[string]interface{}{}
 		}
 		items := common.GetSlice(data, "items")
+		// Strip avatar from meta_data — not useful for AI agents.
+		for _, raw := range items {
+			if m, ok := raw.(map[string]interface{}); ok {
+				if meta, ok := m["meta_data"].(map[string]interface{}); ok {
+					delete(meta, "avatar")
+				}
+			}
+		}
 		outData := map[string]interface{}{
 			"items":      items,
-			"total":      data["total"],
 			"has_more":   data["has_more"],
 			"page_token": data["page_token"],
 		}

skill-template/domains/doc.md

@@ -86,8 +86,8 @@ Drive Folder (云空间文件夹)
 
 ## 重要说明：画板编辑
 > **⚠️ lark-doc skill 不能直接编辑已有画板内容，但 `docs +update` 可以新建空白画板**
-### 场景 1：已通过 docs +fetch --api-version v2 获取到文档内容和画板 token
-如果用户已经通过 `docs +fetch --api-version v2` 拉取了文档内容，并且文档中已有画板（返回的 markdown 中包含 `<whiteboard token="xxx"/>` 标签），请引导用户：
+### 场景 1：已通过 docs +fetch 获取到文档内容和画板 token
+如果用户已经通过 `docs +fetch` 拉取了文档内容，并且文档中已有画板（返回的 markdown 中包含 `<whiteboard token="xxx"/>` 标签），请引导用户：
 1. 记录画板的 token
 2. 查看 [`../lark-whiteboard/SKILL.md`](../lark-whiteboard/SKILL.md) 了解如何编辑画板内容
 ### 场景 2：刚创建画板，需要编辑

skill-template/domains/drive.md

@@ -111,7 +111,7 @@ Drive Folder (云空间文件夹)
 
 | 操作 | 需要的 Token | 说明 |
 |------|-------------|------|
-| 读取文档内容 | `file_token` / 通过 `docs +fetch --api-version v2` 自动处理 | `docs +fetch --api-version v2` 支持直接传入 URL |
+| 读取文档内容 | `file_token` / 通过 `docs +fetch` 自动处理 | `docs +fetch` 支持直接传入 URL |
 | 添加局部评论（划词评论） | `file_token` | 传 `--block-id` 时，`drive +add-comment` 会创建局部评论；`docx` 支持文本定位或 block_id，`sheet` 使用 `<sheetId>!<cell>`，`slides` 使用 `<slide-block-type>!<xml-id>`；Base / bitable 只有记录局部评论，定位为 file_token(base token) + `--block-id <table-id>!<record-id>!<view-id>` |
 | 添加全文评论 | `file_token` | 不传 `--block-id` 时，`drive +add-comment` 默认创建全文评论；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc`/`docx`/`file` 的 wiki URL |
 | 下载文件 | `file_token` | 从文件 URL 中直接提取 |

skills/lark-calendar/SKILL.md

@@ -31,6 +31,8 @@ lark-cli calendar +agenda --as user
 | Shortcut | 说明 |
 |----------|------|
 | [`+agenda`](references/lark-calendar-agenda.md) | 查看日程安排（默认今天） |
+| [`+search-event`](references/lark-calendar-search-event.md) | 按关键词、时间范围和参会人搜索日程, 仅返回 日程ID/主题/时间等信息，详情需走 `events get` |
+| [`+meeting`](references/lark-calendar-meeting.md) | 通过日程事件 ID 获取关联的视频会议信息（meeting_id、meeting_note），日程开过视频会议才会有meeting_id |
 | [`+create`](references/lark-calendar-create.md) | 创建日程并邀请参会人（ISO 8601 时间） |
 | [`+update`](references/lark-calendar-update.md) | 更新既有日程字段，或独立增量添加/移除参会人和会议室 |
 | [`+freebusy`](references/lark-calendar-freebusy.md) | 查询用户主日历的忙闲信息和 RSVP 状态 |
@@ -53,6 +55,7 @@ lark-cli calendar +agenda --as user
 - **全天日程（All-day Event）**：只按日期占用、没有具体起止时刻的日程，结束日期是包含在日程时间内的。
 - **时间块 vs 时间范围**：时间块是具体确定的连续时间段（如 `14:00~15:00`），时间范围是泛指（如"今天下午"）。`+room-find` 必须基于确定时间块，不能基于模糊范围。
 - **会议室（Room）**："room"不是"房间"，是"会议室"。会议室是日程的一种参与人（resource attendee），不能脱离日程单独预定。
+- **日程会议 ID（Meeting ID）**：日程的历史视频会议 ID，在日程上开过视频会议才会有。
 
 ## 术语映射
 
@@ -64,6 +67,9 @@ lark-cli calendar +agenda --as user
 |----------|--------|
 | 查询过去的会议（"昨天的会议""上周的会"） | [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md)（会议数据含即时会议，仅查日程会遗漏） |
 | 查询日历/日程或未来时间的会议 | 本 skill |
+| 按关键词搜索日程 | 本 skill（`+search-event`） |
+| 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（`+meeting`） |
+| 从日程进一步拿 AI 智能纪要 / 逐字稿 / 妙记产物 | 先 `+meeting` 取 `meeting_id`，再 [`vc +detail`](../lark-vc/references/lark-vc-detail.md) → [`note +detail`](../lark-note/references/lark-note-detail.md) / [`minutes +detail`](../lark-minutes/references/lark-minutes-detail.md) |
 | 预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
 
 ## 任务类型分流
@@ -115,7 +121,6 @@ lark-cli calendar <resource> <method> [flags]
   - `get` — 获取日程
   - `instance_view` — 查询日程视图
   - `patch` — 更新日程
-  - `search_event` — 搜索日程（仅返回 日程ID/主题/时间，详情需走 `events get`）
   - `share_info` — 获取日程分享链接
 
 ### freebusys

skills/lark-calendar/references/lark-calendar-meeting.md

@@ -0,0 +1,40 @@
+
+# calendar +meeting
+
+通过日程 ID（`event_id`） 获取关联的视频会议信息（`meeting_id`、`meeting_note`）。只读。
+
+## 命令
+
+```bash
+# 单个 / 批量（逗号分隔，最多 50 个）
+lark-cli calendar +meeting --event-ids <event_id1>,<event_id2>
+
+# 默认使用主日历，需要时显式传 --calendar-id
+lark-cli calendar +meeting --event-ids <event_id> --calendar-id <calendar_id>
+```
+
+## 输出字段
+
+| 字段 | 说明 |
+|------|------|
+| `event_id` | 日程 ID |
+| `meeting_id` | 关联的视频会议 ID |
+| `meeting_note` | 用户主动绑定到日程的纪要文档 Token（`MeetingNotes`，由用户在日程页手动添加；）。**与会中产生的 AI 智能纪要 `note_doc_token` 是两份不同文档**，要拿 AI 纪要请继续走 `vc +detail` → `note +detail`。 |
+
+## 下游链路
+
+`calendar +meeting` 只把日程 ID 翻译为 `meeting_id` / `meeting_note`，要拿会中产生的产物（AI 智能纪要、逐字稿、妙记）需继续调用：
+
+```bash
+# 1. meeting_id → note_id + minute_token（同一会议两份产物，可能各自为空）
+lark-cli vc +detail --meeting-ids <meeting_id>
+
+# 2a. note_id → 纪要文档 token（note_doc_token / verbatim_doc_token / shared_doc_tokens）
+lark-cli note +detail --note-id <note_id>
+
+# 2b. minute_token → 妙记 AI 产物（按需获取，不传不返回任何 AI 内容）
+lark-cli minutes +detail --minute-tokens <minute_token> --summary --todo --chapter --keyword --transcript
+
+# 3. 任意文档 token（meeting_note / note_doc_token / verbatim_doc_token / shared_doc_token）→ 正文
+lark-cli docs +fetch --api-version v2 --doc <doc_token> --doc-format markdown
+```

skills/lark-calendar/references/lark-calendar-schedule-meeting.md

@@ -75,7 +75,7 @@
 
 定位规则：
 
-- 优先利用用户给出的标题、日期、时间范围、`这个日程/这场会` 等锚点，通过 `+agenda`、`events search_event` 或实例视图缩小范围。
+- 优先利用用户给出的标题、日期、时间范围、`这个日程/这场会` 等锚点，通过 `+agenda`、`+search-event` 或实例视图缩小范围。
 - 如果命中多个候选日程，必须向用户展示候选项并要求确认，禁止自行猜测。
 - 如果是重复性日程的某一次实例，必须继续定位到该次实例的 `event_id`。
 

skills/lark-calendar/references/lark-calendar-search-event.md

@@ -0,0 +1,29 @@
+
+# calendar +search-event
+
+按关键词、时间范围和参会人搜索日历日程。只读。
+
+## 命令
+
+```bash
+# 按关键词
+lark-cli calendar +search-event --query "周会"
+
+# 按时间范围（ISO 8601 或 YYYY-MM-DD）
+lark-cli calendar +search-event --start "2026-04-20T00:00:00+08:00" --end "2026-04-27T23:59:59+08:00"
+
+# 按参会人（自动识别 ou_ 用户 / oc_ 群聊 / omm_ 会议室前缀）
+lark-cli calendar +search-event --attendee-ids "ou_user1,oc_chat1,omm_room1"
+
+# 组合
+lark-cli calendar +search-event --query "周会" --start 2026-04-20 --end 2026-04-27 --attendee-ids "ou_user1"
+```
+
+## 输出字段
+
+`items` 列表每条返回 `event_id` / `summary` / `start` / `end` / `is_all_day` / `app_link`；外层有 `has_more`、`page_token`。**仅返回基础字段，要拿日程详情用 `calendar events get`。**
+
+## 注意事项
+
+- 分页：`has_more=true` 时持续用 `page_token` 翻页直到 false，不要遗漏；`page-size` 最大 30。
+- 已结束的会议优先用 `vc +search`——日历不收录"即时会议"，只查日程会漏。

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

@@ -65,7 +65,7 @@ lark-cli calendar +update \
 - 只想修改标题、描述、时间或重复规则时，不需要同时传 `--add-attendee-ids` 或 `--remove-attendee-ids`。
 - 如需替换某个参与人、群组或会议室，使用 `--remove-attendee-ids <旧ID>` + `--add-attendee-ids <新ID>`。
 - 会议室是 resource attendee，必须使用 `omm_` ID 添加到参会人列表，不能脱离日程单独预定。
-- 更新重复性日程的某一次实例时，必须先通过 `+agenda`、`events search_event` 或实例视图定位该实例的 `event_id`。
+- 更新重复性日程的某一次实例时，必须先通过 `+agenda`、`+search-event` 或实例视图定位该实例的 `event_id`。
 - 如果需要验证更新结果，等待至少 2 秒后再查询，避免同步延迟导致读到旧数据。
 - 当同一次命令组合多个动作时，执行顺序为“日程字段 -> 移除参会人 -> 添加参会人”。若中途失败，不会自动回滚已成功步骤；错误信息会说明已完成的步骤。
 

skills/lark-doc/SKILL.md

@@ -1,31 +1,29 @@
 ---
 name: lark-doc
 version: 2.0.0
-description: "飞书云文档（Docx / Wiki 文档，v2 API）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。不负责文档评论管理，也不负责表格或 Base 的数据操作。"
+description: "飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。不负责文档评论管理，也不负责表格或 Base 的数据操作。"
 metadata:
   requires:
     bins: ["lark-cli"]
-  cliHelp: "lark-cli docs --api-version v2 --help; lark-cli docs +create --api-version v2 --help; lark-cli docs +fetch --api-version v2 --help; lark-cli docs +update --api-version v2 --help; lark-cli docs +resource-download --help; lark-cli docs +resource-update --help; lark-cli docs +resource-delete --help"
+  cliHelp: "lark-cli docs --help; lark-cli docs +create --help; lark-cli docs +fetch --help; lark-cli docs +update --help; lark-cli docs +resource-download --help; lark-cli docs +resource-update --help; lark-cli docs +resource-delete --help"
 ---
 
-# docs (v2)
+# docs
 
 **身份：文档操作默认使用 `--as user`。首次使用前执行 `lark-cli auth login`。**
 
-> **CRITICAL — API 版本：本 skill 使用 v2 API。执行 `docs +create`、`docs +fetch`、`docs +update` 时必须显式传入 `--api-version v2`。**
-
 ```bash
 # 常用示例
-lark-cli docs +fetch  --api-version v2 --doc "文档URL或token"
-lark-cli docs +create --api-version v2 --content '<title>标题</title><p>内容</p>'
-lark-cli docs +update --api-version v2 --doc "文档URL或token" --command append --content '<p>内容</p>'
+lark-cli docs +fetch --doc "文档URL或token"
+lark-cli docs +create --content '<title>标题</title><p>内容</p>'
+lark-cli docs +update --doc "文档URL或token" --command append --content '<p>内容</p>'
 ```
 
 ## 前置条件 — 执行操作前必读
 
 **CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：**
 1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用）
-2. **读取文档（`docs +fetch --api-version v2`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
+2. **读取文档（`docs +fetch`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
 3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）和 [`lark-doc-style.md`](references/style/lark-doc-style.md)（元素选择、丰富度规则、颜色语义）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update.md`](references/lark-doc-update.md) 和 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md)
 
 **未读完以上文件就执行相应操作会导致参数选择错误或格式错误。**
@@ -57,7 +55,7 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
 | `<cite type="doc" file-type="sheets" token="..." sheet-id="...">` | 同 `<sheet>` | [`lark-sheets`](../lark-sheets/SKILL.md) |
 | `<cite type="doc" file-type="bitable" token="..." table-id="...">` | 同 `<bitable>` | [`lark-base`](../lark-base/SKILL.md) |
 | `<vc-transcribe-tab vc-node-id="...">` | `vc-node-id` -> note_id | [`lark-note`](../lark-note/SKILL.md)：先 `note +detail --note-id <vc-node-id>` |
-| `<synced_reference src-token="..." src-block-id="...">` | `src-token` -> doc_token, `src-block-id` -> block_id | 用 `docs +fetch --api-version v2` 读取 src-token 文档，定位 block |
+| `<synced_reference src-token="..." src-block-id="...">` | `src-token` -> doc_token, `src-block-id` -> block_id | 用 `docs +fetch` 读取 src-token 文档，定位 block |
 
 ## Shortcuts（推荐优先使用）
 

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

@@ -15,10 +15,10 @@
 
 ```bash
 # 创建 XML 文档（默认格式，推荐）
-lark-cli docs +create --api-version v2 --content '<title>项目计划</title><h1>目标</h1><p>记录本周重点。</p>'
+lark-cli docs +create --content '<title>项目计划</title><h1>目标</h1><p>记录本周重点。</p>'
 
 # 仅当用户明确要求导入 Markdown 时才使用；文档标题用 --title，正文标题按内容自然组织
-lark-cli docs +create --api-version v2 --doc-format markdown --title "项目计划" --content $'## 目标\n\n- 明确重点\n- 记录待办'
+lark-cli docs +create --doc-format markdown --title "项目计划" --content $'## 目标\n\n- 明确重点\n- 记录待办'
 ```
 
 ## 返回值
@@ -58,7 +58,6 @@ lark-cli docs +create --api-version v2 --doc-format markdown --title "项目计
 
 | 参数                  | 必填 | 说明                                          |
 | ------------------- | -- |---------------------------------------------|
-| `--api-version`     | 是  | 固定传 `v2`                                    |
 | `--title`           | 否  | 文档标题，Markdown 导入时使用；XML 创建推荐在 `--content` 开头写 `<title>...</title>`；多个标题仅保留第一个并在 `warnings` / `degrade_details` 提示 |
 | `--content`         | 视情况 | 文档内容（XML 或 Markdown 格式）；不传 `--content` 时必须传 `--title` |
 | `--doc-format`      | 否  | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |

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

@@ -5,27 +5,27 @@
 
 ```bash
 # 获取文档（默认 XML，simple）
-lark-cli docs +fetch --api-version v2 --doc "https://xxx.feishu.cn/docx/Z1Fj...tnAc"
+lark-cli docs +fetch --doc "https://xxx.feishu.cn/docx/Z1Fj...tnAc"
 
 # Markdown 格式
-lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc --doc-format markdown
+lark-cli docs +fetch --doc Z1Fj...tnAc --doc-format markdown
 
 # 带 block ID（用于后续 block 级更新）
-lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc --detail with-ids
+lark-cli docs +fetch --doc Z1Fj...tnAc --detail with-ids
 
 # 只拿目录
-lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc --scope outline --max-depth 3
+lark-cli docs +fetch --doc Z1Fj...tnAc --scope outline --max-depth 3
 
 # 按 block id 区间精读
-lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
+lark-cli docs +fetch --doc Z1Fj...tnAc \
   --scope range --start-block-id blkA --end-block-id blkB --detail with-ids
 
 # 读整个章节（以标题 id 为锚点，自动展开到下一个同级/更高级标题前）
-lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
+lark-cli docs +fetch --doc Z1Fj...tnAc \
   --scope section --start-block-id <标题id> --detail with-ids
 
 # 按关键词定位（多关键词用 | 分隔，任一命中即返回）
-lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
+lark-cli docs +fetch --doc Z1Fj...tnAc \
   --scope keyword --keyword "部署|发布|上线"
 ```
 
@@ -97,7 +97,6 @@ lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--api-version` | 是 | 固定传 `v2` |
 | `--doc` | 是 | 文档 URL 或 token（支持 `/docx/` 和 `/wiki/`） |
 | `--doc-format` | 否 | `xml`（默认）\| `markdown` \| `im-markdown`（仅用于获取内容后在 `lark-im` 场景下使用） |
 | `--detail` | 否 | `simple`（默认）\| `with-ids` \| `full` |
@@ -128,7 +127,7 @@ lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
 
 ## 嵌入电子表格 / 多维表格
 
-返回中可能含 `<sheet>`、`<bitable>`、`<cite file-type="sheets|bitable">`。内部数据无法通过 `docs +fetch --api-version v2` 获取，提取 `token` 等属性后切到 [`lark-sheets`](../../lark-sheets/SKILL.md) / [`lark-base`](../../lark-base/SKILL.md) 下钻，详见 [SKILL.md 快速决策](../SKILL.md) 路由表。
+返回中可能含 `<sheet>`、`<bitable>`、`<cite file-type="sheets|bitable">`。内部数据无法通过 `docs +fetch` 获取，提取 `token` 等属性后切到 [`lark-sheets`](../../lark-sheets/SKILL.md) / [`lark-base`](../../lark-base/SKILL.md) 下钻，详见 [SKILL.md 快速决策](../SKILL.md) 路由表。
 
 ## 参考
 

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

@@ -1,6 +1,6 @@
 # Markdown 格式参考
 
-`docs +fetch --api-version v2` / `docs +create --api-version v2` / `docs +update --api-version v2` 使用 `--doc-format markdown` 时适用；fetch 的 `--doc-format im-markdown` 仅用于获取内容后在 `lark-im` 场景下使用，不作为 create/update 写入格式。
+`docs +fetch` / `docs +create` / `docs +update` 使用 `--doc-format markdown` 时适用；fetch 的 `--doc-format im-markdown` 仅用于获取内容后在 `lark-im` 场景下使用，不作为 create/update 写入格式。
 
 ## 转义规则
 
@@ -34,14 +34,14 @@
 - `$...$` 数学公式内部，符号为 LaTeX 语法，不受 Markdown 转义影响
 
 **导出已转义，不要反转义：**
-`docs +fetch --api-version v2 --doc-format markdown` 导出的内容中，特殊字符**已经被转义过了**（例如 `\[`、`\|`、`\\` 等）。这些 `\` 是有意义的——去掉会导致后续写入时字符被 Markdown 语法吞掉。**不要反转义或去掉 `\`。**
+`docs +fetch --doc-format markdown` 导出的内容中，特殊字符**已经被转义过了**（例如 `\[`、`\|`、`\\` 等）。这些 `\` 是有意义的——去掉会导致后续写入时字符被 Markdown 语法吞掉。**不要反转义或去掉 `\`。**
 
 **写入时必须转义：**
 使用 `docs +create` 或 `docs +update` 的 `--doc-format markdown` 写入内容时，字面文本中的特殊字符同样必须转义。`--pattern` 参数中也必须使用转义形式才能正确匹配。
 
 **导出 → 更新 工作流示例：**
 
-1. `docs +fetch --api-version v2` 导出得到 `C:\\Users\\test\[1\]`
+1. `docs +fetch` 导出得到 `C:\\Users\\test\[1\]`
 2. 用 `str_replace --pattern 'C:\\Users\\test\[1\]'` 匹配（直接使用导出的转义形式）
 3. `--content` 中的替换内容也要保持转义：`C:\\Users\\prod\[2\]`
 

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

@@ -48,7 +48,7 @@ lark-cli docs +media-insert --doc doxcnXXX --from-clipboard
 
 # 从本地文件插入
 # 除了上传本地文件，还可以在 `docs +update` 时直接通过网络 URL 插入图片，无需先下载到本地：
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_insert_after \
+lark-cli docs +update --doc "<doc_id>" --command block_insert_after \
   --block-id "目标 block_id" \
   --content '<img href="https://example.com/photo.png"/>'
 

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

@@ -14,13 +14,12 @@
 > - **局部精修**（`str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after`）：优先使用 XML（默认）。XML 能稳定表达 block 结构和样式，精准编辑更可控；不要因为 Markdown 写起来更简单就自行切换。
 > - **整段写入**（`append` / `overwrite`）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件或明确要求 Markdown 时直接用 Markdown；否则默认 XML。
 >
-> **Markdown 局限 & block ID 前提：** Markdown 不携带 block ID，也无样式（颜色、对齐、callout 等）。需要按 block ID 定位（`block_*` 指令的 `--block-id`）时，先 `docs +fetch --api-version v2 --detail with-ids` **配合 `--scope`（`outline` / `range` / `keyword` / `section`）局部获取**目标段落，不要全量 fetch。拿到 block ID 后 `--content` 仍可用 Markdown，只是写入内容不带样式。
+> **Markdown 局限 & block ID 前提：** Markdown 不携带 block ID，也无样式（颜色、对齐、callout 等）。需要按 block ID 定位（`block_*` 指令的 `--block-id`）时，先 `docs +fetch --detail with-ids` **配合 `--scope`（`outline` / `range` / `keyword` / `section`）局部获取**目标段落，不要全量 fetch。拿到 block ID 后 `--content` 仍可用 Markdown，只是写入内容不带样式。
 
 ## 参数
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--api-version` | 是 | 固定传 `v2` |
 | `--doc` | 是 | 文档 URL 或 token |
 | `--command` | 是 | 操作指令（见下方指令速查表） |
 | `--doc-format` | 否 | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |
@@ -64,20 +63,20 @@
 
 ```bash
 # 简单文本替换
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
+lark-cli docs +update --doc "<doc_id>" --command str_replace \
   --pattern "张三" --content "李四"
 
 # 替换为富文本（加粗 + 链接）
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
+lark-cli docs +update --doc "<doc_id>" --command str_replace \
   --pattern "旧链接" --content '<b>新链接</b> <a href="https://example.com">点击查看</a>'
 
 # 仅当用户明确要求时才使用 Markdown
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
+lark-cli docs +update --doc "<doc_id>" --command str_replace \
   --doc-format markdown --pattern "旧内容" --content "新内容"
 
 # Markdown 模式下支持跨行匹配（--pattern 与 --content 都需要真实换行；"..."/'...' 里的 \n 是字面量）
 # 多行内容推荐 heredoc 或 --content @file.md，避免 shell 转义踩坑
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
+lark-cli docs +update --doc "<doc_id>" --command str_replace \
   --doc-format markdown \
   --pattern "$(printf '## 旧标题\n\n第一段原文\n\n第二段原文')" \
   --content - <<'EOF'
@@ -90,7 +89,7 @@ EOF
 
 # Markdown 模式下使用 `前缀...后缀` 省略号匹配首尾特征明显的大段内容
 # 下例会把「## 旧标题」到「结束语。」之间的所有内容整体替换
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
+lark-cli docs +update --doc "<doc_id>" --command str_replace \
   --doc-format markdown \
   --pattern "## 旧标题...结束语。" \
   --content - <<'EOF'
@@ -102,14 +101,14 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
 EOF
 
 # 删除文本：--content 传空字符串即可
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
+lark-cli docs +update --doc "<doc_id>" --command str_replace \
   --pattern "废弃的内容" --content ""
 ```
 
 ### block_insert_after — 在指定 block 之后插入
 
 ```bash
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_insert_after \
+lark-cli docs +update --doc "<doc_id>" --command block_insert_after \
   --block-id "目标 block_id" \
   --content '<h2>新章节</h2><ul><li>要点 1</li><li>要点 2</li></ul>'
 ```
@@ -117,7 +116,7 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_insert_a
 ### block_replace — 替换指定 block
 
 ```bash
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_replace \
+lark-cli docs +update --doc "<doc_id>" --command block_replace \
   --block-id "目标 block_id" \
   --content '<p>替换后的段落内容</p>'
 ```
@@ -126,14 +125,14 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_replace
 
 ```bash
 # 删除多个块时用逗号 "," 分隔
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_delete \
+lark-cli docs +update --doc "<doc_id>" --command block_delete \
   --block-id "block_id_1,block_id_2,block_id_3"
 ```
 
 ### overwrite — 全文覆盖
 
 ```bash
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command overwrite \
+lark-cli docs +update --doc "<doc_id>" --command overwrite \
   --content '<title>全新文档</title><h1>概述</h1><p>新的内容</p>'
 ```
 
@@ -142,7 +141,7 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command overwrite \
 ### append — 在文档末尾追加
 
 ```bash
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command append \
+lark-cli docs +update --doc "<doc_id>" --command append \
   --content '<h2>新增章节</h2><p>追加的内容</p>'
 ```
 
@@ -154,7 +153,7 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command append \
 
 ```bash
 # 复制多个块（按顺序插入：anchor → a → b → c）
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_copy_insert_after \
+lark-cli docs +update --doc "<doc_id>" --command block_copy_insert_after \
   --block-id "锚点 block_id" \
   --src-block-ids "block_a,block_b,block_c"
 ```
@@ -165,7 +164,7 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_copy_ins
 
 ```bash
 # 移动到页面末尾
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_move_after \
+lark-cli docs +update --doc "<doc_id>" --command block_move_after \
   --block-id "-1表示末尾，page_id表示开头，blk" \
   --src-block-ids "block_a,block_b"
 ```
@@ -203,7 +202,7 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_move_aft
 
 1. **获取文档内容和 block ID**：
    ```bash
-   lark-cli docs +fetch --api-version v2 --doc "<doc_id>" --detail with-ids
+   lark-cli docs +fetch --doc "<doc_id>" --detail with-ids
    ```
 
 2. **定位目标 block**：从返回的 XML 中找到要修改的 block 及其 `id` 属性
@@ -211,11 +210,11 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_move_aft
 3. **执行更新**：
    ```bash
    # 替换特定 block
-   lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_replace \
+   lark-cli docs +update --doc "<doc_id>" --command block_replace \
      --block-id "blkcnXXXX" --content "<p>新内容</p>"
 
    # 在某 block 后插入
-   lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_insert_after \
+   lark-cli docs +update --doc "<doc_id>" --command block_insert_after \
      --block-id "blkcnXXXX" --content "<h2>追加的章节</h2>"
    ```
 
@@ -224,13 +223,13 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_move_aft
 不需要 block ID，直接匹配替换：
 
 ```bash
-lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
+lark-cli docs +update --doc "<doc_id>" --command str_replace \
   --pattern "v1.0" --content "v2.0"
 ```
 
 ## 画板处理
 
-> **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch --api-version v2` 取到 `<whiteboard token="...">`，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 读取 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 并写入。
+> **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch` 取到 `<whiteboard token="...">`，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 读取 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 并写入。
 
 画板的语法选型与插入示例见 [`lark-doc-style.md`](style/lark-doc-style.md) 的「画板语法与插入」章节。
 

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

@@ -23,7 +23,7 @@
 |-------------------------|-----------------------------------------------------------|
 | 文档中需要思维导图、时序图、类图、饼图、甘特图 | 步骤 2A:使用 mermaid 插入图表                                     |
 | 文档中需要插入其他图表/自定义图形       | 步骤 2B: 使用 SVG 插入图表                                        |
-| 已有画板需要更新内容              | 先 `docs +fetch --api-version v2` 获取 `board_token`，跳至步骤 3B |
+| 已有画板需要更新内容              | 先 `docs +fetch` 获取 `board_token`，跳至步骤 3B |
 | 只查看 / 下载已有画板            | 切换至 `lark-whiteboard`，不走本流程                               |
 
 > [!IMPORTANT]
@@ -46,7 +46,7 @@ SubAgent 插入 SVG。
 
 ### 步骤 2B: SubAgent 使用 SVG 插入图表
 
-主 Agent 启动 SubAgent，让它用 `docs +create --api-version v2` / `docs +update --api-version v2` 插入：
+主 Agent 启动 SubAgent，让它用 `docs +create` / `docs +update` 插入：
 
 ```xml
 

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

@@ -20,7 +20,7 @@
 
 1. 分析用户需求：受众、目的、范围
 2. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
-3. `docs +create --api-version v2` 创建文档。长文档可**只建骨架**：标题 + 各级标题 + 每节一句占位摘要；短文档可以一次写入完整内容
+3. `docs +create` 创建文档。长文档可**只建骨架**：标题 + 各级标题 + 每节一句占位摘要；短文档可以一次写入完整内容
    - ⚠️ 创建较长文档时，**不要**一次性把完整章节内容塞进 `--content`。超长 `--content` 容易触发字符/参数限制。
    - 完整内容留到步骤二，由各 Agent 用 `block_insert_after --block-id <章节标题 block_id>` 分段写入。
    - ⚠️ **`@file` 路径限制**：`--content @file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下，用完自行清理。
@@ -34,7 +34,7 @@
 
 ### 步骤三：整合审查与画板识别（串行）
 
-5. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果
+5. `docs +fetch --detail with-ids` 获取文档，审查整体效果
 6. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材
 7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
 

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

@@ -19,10 +19,10 @@
 ### 步骤一：分析与画板识别（串行）
 
 1. **选择读取范围**（节省上下文的关键）：
-   - 用户只改某一节 / 文档较大 → 先 `docs +fetch --api-version v2 --scope outline --max-depth 2` 拿目录，再 `docs +fetch --api-version v2 --scope section --start-block-id <目标标题id> --detail with-ids` 精读该节（`section` 会自动展开到下一个同级/更高级标题前，不用手动算结束 block id）
-   - 需要精确跨节区间 → `docs +fetch --api-version v2 --scope range --start-block-id xxx --end-block-id yyy`（或 `--end-block-id -1` 读到末尾）
-   - 用户只给了模糊关键词 → `docs +fetch --api-version v2 --scope keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids`
-   - 用户明确要改整篇 → `docs +fetch --api-version v2 --detail with-ids`
+   - 用户只改某一节 / 文档较大 → 先 `docs +fetch --scope outline --max-depth 2` 拿目录，再 `docs +fetch --scope section --start-block-id <目标标题id> --detail with-ids` 精读该节（`section` 会自动展开到下一个同级/更高级标题前，不用手动算结束 block id）
+   - 需要精确跨节区间 → `docs +fetch --scope range --start-block-id xxx --end-block-id yyy`（或 `--end-block-id -1` 读到末尾）
+   - 用户只给了模糊关键词 → `docs +fetch --scope keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids`
+   - 用户明确要改整篇 → `docs +fetch --detail with-ids`
    - 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) "意图引导：选择正确的 --scope"
 2. 系统性评估：用户想改什么、现有文档风格是什么、哪些内容需要保留、哪些问题影响理解
 3. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断哪些段落的信息适合用图表达。重要信息优先画板化，记录需要插图的章节（block ID）、推荐画板类型、mermaid/SVG路径和源内容片段
@@ -52,4 +52,4 @@ SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、
 
 已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。
 
-**上下文节省提示**：Agent 如需在自己负责的章节内重新读取内容，优先用 `docs +fetch --api-version v2 --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉自己的章节，不要重复拉全文。
+**上下文节省提示**：Agent 如需在自己负责的章节内重新读取内容，优先用 `docs +fetch --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉自己的章节，不要重复拉全文。

skills/lark-drive/SKILL.md

@@ -69,7 +69,7 @@ lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
 
 | 操作 | 需要的 Token | 说明 |
 |------|-------------|------|
-| 读取文档内容 | `file_token` / 通过 `docs +fetch --api-version v2` 自动处理 | `docs +fetch --api-version v2` 支持直接传入 URL |
+| 读取文档内容 | `file_token` / 通过 `docs +fetch` 自动处理 | `docs +fetch` 支持直接传入 URL |
 | 添加局部评论（划词评论） | `file_token` | 传 `--block-id` 时，`drive +add-comment` 会创建局部评论；`docx` 支持文本定位或 block_id，`sheet` 使用 `<sheetId>!<cell>`，`slides` 使用 `<slide-block-type>!<xml-id>`；Base 只有记录局部评论，定位为 file_token(base_token) + `--block-id <table-id>!<record-id>!<view-id>` |
 | 添加全文评论 | `file_token` | 不传 `--block-id` 时，`drive +add-comment` 默认创建全文评论；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc`/`docx`/`file` 的 wiki URL |
 | 下载文件 | `file_token` | 从文件 URL 中直接提取 |

skills/lark-drive/references/lark-drive-add-comment.md

@@ -35,7 +35,7 @@ lark-cli drive +add-comment \
   --doc "<FILE_TOKEN>" --type file \
   --content '[{"type":"text","text":"请补充目录说明"}]'
 
-# 给 docx 文档的指定 block 添加局部评论（block_id 可通过 docs +fetch --api-version v2 --detail with-ids 获取）
+# 给 docx 文档的指定 block 添加局部评论（block_id 可通过 docs +fetch --detail with-ids 获取）
 lark-cli drive +add-comment \
   --doc "https://example.larksuite.com/docx/<DOC_ID>" \
   --block-id "<BLOCK_ID>" \
@@ -155,11 +155,11 @@ lark-cli drive +add-comment \
 | `--type` | 裸 token 时必填 | 文档类型：`doc`、`docx`、`file`、`sheet`、`slides`、`bitable`、`base`；评论 Base 文档推荐传 `bitable`，`base` 仅作为兼容别名兜底。URL 输入时自动识别，无需传 |
 | `--content` | 是 | `reply_elements` JSON 数组字符串。示例：`'[{"type":"text","text":"文本"},{"type":"mention_user","text":"ou_xxx"},{"type":"link","text":"https://example.com"}]'` |
 | `--full-comment` | 否 | 显式指定创建全文评论；未传 `--block-id` 时也会默认走全文评论（仅适用于 doc/docx、白名单 Drive file，以及解析为这些类型的 wiki；不适用于 sheet、slides、Base / bitable） |
-| `--block-id` | 局部评论时必填 | 目标块 ID，可通过 `docs +fetch --api-version v2 --detail with-ids` 获取；sheet 用 `<sheetId>!<cell>`，slides 用 `<slide-block-type>!<xml-id>`，Base 用 `<table-id>!<record-id>!<view-id>` |
+| `--block-id` | 局部评论时必填 | 目标块 ID，可通过 `docs +fetch --detail with-ids` 获取；sheet 用 `<sheetId>!<cell>`，slides 用 `<slide-block-type>!<xml-id>`，Base 用 `<table-id>!<record-id>!<view-id>` |
 
 ## 行为说明
 
-- **局部评论需要先获取 block ID**：先调用 `docs +fetch --api-version v2 --doc <TOKEN> --detail with-ids` 获取带有 block ID 的文档内容，然后使用 `--block-id` 指定目标块。
+- **局部评论需要先获取 block ID**：先调用 `docs +fetch --doc <TOKEN> --detail with-ids` 获取带有 block ID 的文档内容，然后使用 `--block-id` 指定目标块。
 - **Review 场景优先局部评论**：审阅、校对、逐条指出问题时，必须先尝试定位到具体 block / 单元格 / slide 元素，并逐问题创建局部评论；不要把所有问题合并成一条全文评论。
 - 未传 `--block-id` 时，shortcut 默认创建**全文评论**；也可以显式传 `--full-comment`。全文评论支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终可解析为 `doc`/`docx`/`file` 的 wiki URL。
 - **Drive file 评论**：仅支持白名单扩展名的普通文件。当前支持：`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。

skills/lark-drive/references/lark-drive-comment-location.md

@@ -27,7 +27,7 @@ lark-cli drive file.comments batch_query \
 同时获取文档内容，并要求返回 block id：
 
 ```bash
-lark-cli docs +fetch --api-version v2 --doc '<doc_token_or_url>' --detail with-ids
+lark-cli docs +fetch --doc '<doc_token_or_url>' --detail with-ids
 ```
 
 ## 字段含义
@@ -127,7 +127,7 @@ lark-cli docs +fetch --api-version v2 --doc '<doc_token_or_url>' --detail with-i
 
 1. 确认目标是 `file_type=docx`；只有 docx 文档支持通过 `need_relation` 查询评论位置。
 2. 用 `drive file.comments list` 或 `drive file.comments batch_query` 获取评论，并带 `need_relation=true`。
-3. 用 `docs +fetch --api-version v2 --detail with-ids` 获取文档内容。
+3. 用 `docs +fetch --detail with-ids` 获取文档内容。
 4. 对每条评论先看 `relation`：
    - 如果存在 `relation.relation`，解析这个 JSON 字符串。
    - 从解析结果里取 `positionInfo.blockID`。

skills/lark-drive/references/lark-drive-files-list.md

@@ -10,7 +10,7 @@
 | 盘点用户明确确认的 Drive 根目录 | 使用 | 第一层用空 `folder_token`，子文件夹继续按普通文件夹递归 |
 | 验证移动 / 创建后的实际位置 | 使用 | 读取目标目录直接子项，再按需递归验证 |
 | 根据关键词、标题、时间、owner 找资源 | 不使用 | 优先用 `drive +search` |
-| 读取 Docx 正文内容 | 不使用 | 用 `docs +fetch --api-version v2` |
+| 读取 Docx 正文内容 | 不使用 | 用 `docs +fetch` |
 | 读取 Sheet / Base 内部数据 | 不使用 | 切到 `lark-sheets` / `lark-base` |
 
 ## 标准命令模板

skills/lark-minutes/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-minutes
 version: 1.0.0
-description: "飞书妙记：搜索妙记列表、查看妙记基础信息、下载妙记音视频文件、上传音视频生成妙记、更新妙记标题、替换说话人。当需要获取、操作或者生成妙记时使用。也支持将本地音视频文件转成纪要和逐字稿（优先使用本 skill，不要用 ffmpeg/whisper 本地转写）。不负责：获取会议关联妙记，或仅按自然语言标题定位纪要"
+description: "飞书妙记：搜索妙记、查看妙记基础信息、下载/上传音视频、读取或编辑妙记的产物内容、改标题、替换说话人/关键词。当给出minute_token、本地音视频文件，要查/改/转妙记产物时使用；本地音视频转纪要/逐字稿优先走本 skill，不要用 ffmpeg/whisper 本地转写。不负责：获取会议关联妙记，或仅按自然语言标题定位纪要"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -27,27 +27,34 @@ metadata:
 | Shortcut | 说明 |
 |----------|------|
 | [`+search`](references/lark-minutes-search.md) | 按关键词、所有者、参与者、时间范围搜索妙记 |
+| [`+detail`](references/lark-minutes-detail.md) | 查询妙记详情(标题和关联的纪要note_id)，按需获取 AI 产物（总结、待办、章节、逐字稿、关键词） |
 | [`+download`](references/lark-minutes-download.md) | 下载妙记音视频媒体文件 |
 | [`+upload`](references/lark-minutes-upload.md) | 上传 file_token 生成妙记 |
 | [`+update`](references/lark-minutes-update.md) | 更新妙记标题 |
-| [`+speaker-replace`](references/lark-minutes-speaker-replace.md) | 替换妙记逐字稿中的说话人（仅支持用户 ID，不支持姓名） |
+| [`+speaker-replace`](references/lark-minutes-speaker-replace.md) | 替换妙记逐字稿中的说话人（须先 `lark-cli api GET .../speakerlist` 取 `speaker_id`） |
+| `+word-replace` | 批量替换逐字稿关键词（详见 `lark-cli minutes +word-replace --help`） |
+| [`+summary`](references/lark-minutes-summary.md) | 替换妙记 AI 总结全文 |
+| [`+todo`](references/lark-minutes-todo.md) | 新建/更新/删除妙记 AI 待办（单条或 `--todos` 批量；不是 lark-task） |
 
 - 使用任何 Shortcut 前，必须先读其对应 reference 文档。
 
 ## 意图路由
 
-| 用户意图 | 路由到 |
-|----------|--------|
-| "我的妙记""搜索妙记""妙记列表" | 本 skill（`+search`） |
-| "这个妙记的标题/时长/封面/链接" | 本 skill（`minutes get`） |
-| "下载妙记的视频/音频" | 本 skill（`+download`） |
-| "把音视频转妙记/上传文件生成妙记" | 本 skill（`+upload`） |
-| "重命名妙记/改妙记标题" | 本 skill（`+update`） |
-| "替换说话人/把 A 的发言改成 B" | 本 skill（`+speaker-replace`） |
-| "这个妙记的逐字稿/总结/待办/章节" | [lark-vc](../lark-vc/SKILL.md)（`vc +notes --minute-tokens`） |
-| "xx 纪要的逐字稿/原始记录/谁说了什么" 且没有 `minute_token` / 妙记 URL / 本地音视频文件 | 不走本 skill；路由到 [lark-drive](../lark-drive/SKILL.md) / [lark-doc](../lark-doc/SKILL.md)，必要时再到 [lark-note](../lark-note/SKILL.md) |
-| "把音视频文件转成纪要/逐字稿/文字稿" | 先本 skill（`+upload`），再 [lark-vc](../lark-vc/SKILL.md)（`vc +notes --minute-tokens`） |
-| 用户同时提到"会议/开会"和"妙记" | 先 [lark-vc](../lark-vc/SKILL.md)（`+search` → `+recording`），再本 skill |
+| 用户意图 | 命令 |
+|---------|------|
+| 我的妙记 / 搜索妙记 / 某段时间的妙记 | `+search` |
+| 妙记基础信息：标题 / 时长 / 封面 / 链接 | `minutes get` |
+| 下载妙记音视频文件、获取媒体下载链接 | `+download`（仅媒体；要妙记内容用 `+detail`） |
+| 妙记总结 / 章节 / 待办 / 关键词 / 逐字稿 | `+detail --minute-tokens <token>` + 显式产物 flag |
+| 基于妙记**提炼/总结/分析/回顾**会议 | `+detail --minute-tokens <token> --transcript`，再独立分析（**禁止照搬 AI 总结**） |
+| 拿这条妙记关联的纪要文档（`note_doc_token` / `verbatim_doc_token` / `shared_doc_tokens`） | `+detail` 取顶层 `note_id` → [`note +detail --note-id`](../lark-note/SKILL.md) |
+| 把本地音视频转纪要 / 逐字稿 / 文字稿 | `drive +upload` 取 `file_token` → `+upload` 生成 `minute_url` → `+detail` 拿产物 |
+| 在妙记里增加 / 更改 / 删除 AI 待办 | `+todo`（**禁止走 lark-task**） |
+| 替换妙记的AI 总结 | `+summary` |
+| 重命名妙记/改妙记标题 | `+update` |
+| 替换说话人/把 A 的发言改成 B/重新归属发言人/把外部（非飞书）说话人改成飞书用户" | 先 `lark-cli api GET .../transcript/speakerlist` 取 `speaker_id`，再 [`minutes +speaker-replace`](references/lark-minutes-speaker-replace.md)；`--from-speaker-id` 只传 id，不传展示名 |
+| 批量替换逐字稿关键词 | `+word-replace` |
+| 用户同时提到"会议/开会"和"妙记" | 先 [lark-vc](../lark-vc/SKILL.md)（`+search` → `+recording`）获取 `minute_token`，再本 skill |
 
 ## 核心概念
 
@@ -58,60 +65,30 @@ metadata:
 
 ### 1. 搜索妙记
 
-1. 当用户描述的是"我的妙记""包含某个关键词的妙记""某段时间内的妙记"，优先使用 `minutes +search`。
-2. 仅支持使用关键词、时间段、参与者、所有者等筛选条件搜索妙记记录，对于不支持的筛选条件，需要提示用户。
-3. 搜索结果存在多条数据时，务必注意分页数据获取，不要遗漏任何妙记记录。
-4. 如果是会议的妙记，应优先通过 [lark-vc](../lark-vc/SKILL.md) 定位会议并获取 `minute_token`。
-5. 会议场景的妙记路由，以及"参与的妙记"如何解释，统一以 [minutes +search](references/lark-minutes-search.md) 为准。
+1. 如果是会议的妙记，应优先通过 [lark-vc](../lark-vc/SKILL.md) 定位会议并获取 `minute_token`。
+2. 会议场景的妙记路由，以及"参与的妙记"如何解释，统一以 [minutes +search](references/lark-minutes-search.md) 为准。
 
 
 ### 2. 查看妙记基础信息
 
 1. 当用户只需要确认某条妙记的标题、封面、时长、所有者、URL 等基础信息时，使用 `minutes minutes get`。
-2. 如果用户给的是妙记 URL，应先从 URL 末尾提取 `minute_token`，再调用 `minutes minutes get`。
-3. 如果是会议 / 日程上下文中的妙记基础信息，先通过 VC 链路拿到 `minute_token`，再调用 `minutes minutes get`。
-4. 用户意图不明确时，默认先给基础元信息，帮助确认是否命中目标妙记。
+2. 如果是会议 / 日程上下文中的妙记基础信息，先通过 VC/Calendar 链路拿到 `minute_token`，再调用 `minutes minutes get`。
+3. 用户意图不明确时，默认先给基础元信息，帮助确认是否命中目标妙记。
 
-> 使用 `lark-cli schema minutes.minutes.get` 可查看完整返回值结构。核心字段包含：`title`（标题）、`cover`（封面 URL）、`duration`（时长，毫秒）、`owner_id`（所有者 ID）、`url`（妙记链接）。
 
-### 3. 下载妙记音视频文件
+### 3. 上传音视频文件生成妙记（并可继续获取纪要 / 逐字稿）
 
-1. 下载妙记音视频文件到本地，或获取有效期 1 天的下载链接。详见 [minutes +download](references/lark-minutes-download.md)。
-2. `+download` 只负责音视频媒体文件。用户需要逐字稿、总结、待办、章节等纪要内容时，请使用 [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md)。
-3. 用户只想拿可分享的下载地址时，使用 `--url-only`；用户要落地到本地文件时，直接下载。
-4. 未显式指定路径时，文件默认落到 `./minutes/{minute_token}/<server-filename>`，与 `vc +notes` 的逐字稿共享同一目录便于聚合。
-
-> **注意**：`+download` 只负责音视频媒体文件。如果用户需要的是逐字稿、总结、待办、章节等纪要内容，请使用 [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md)。
-
-### 4. 读取妙记的逐字稿、总结、待办、章节（只读）
-
-1. 当用户要**查看 / 读取**"这个妙记的逐字稿""总结""待办""章节"时，使用 [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md)。
-2. 如果当前上下文中已有 `minute_token`，可直接传给 `vc +notes`；如果只有妙记 URL，先提取 `minute_token`。
-3. 如果用户给的是**本地音视频文件**，但目标是"转成纪要""转成逐字稿""转成文字稿""转成撰写文字"，应先按下文第 5 节上传文件生成妙记，再把返回的 `minute_url` 提取成 `minute_token`，继续调用 `vc +notes --minute-tokens`。
-4. 用户如果直接给出本地文件名或路径，并要求"转逐字稿""转文字稿""整理成撰写文字"，这也是本 skill 的明确触发信号。
-
-```bash
-# 通过 minute_token 获取纪要产物（逐字稿、总结、待办、章节）
-lark-cli vc +notes --minute-tokens <minute_token>
-```
-
-> **跨 skill 路由**：逐字稿、AI 总结、待办、章节等纪要内容由 [lark-vc](../lark-vc/SKILL.md) 的 `+notes` 命令提供
-> **读 vs 写**：`vc +notes` 只负责**读取** AI 产物。用户要**新建 / 修改 / 删除**妙记内的 AI 待办或替换 AI 总结，见下文第 6 节，**不要**走 [lark-task](../lark-task/SKILL.md)。
-
-### 5. 上传音视频文件生成妙记（并可继续获取纪要 / 逐字稿）
-
-1. 当用户需要通过上传本地音视频文件来生成妙记时使用。
-2. 当用户说"把音视频文件转成纪要""把录音转成逐字稿/文字稿/撰写文字""把 mp4/mp3 转成总结/待办/章节"时，也先走这个入口。
-3. **处理流程**：
+1. 当用户说"把音视频文件转成纪要""把录音转成逐字稿/文字稿/撰写文字""把 mp4/mp3 转成总结/待办/章节"时，也先走这个入口。
+2. **处理流程**：
    - **上传音视频获取 `file_token`**：使用 [`lark-cli drive +upload`](../lark-drive/references/lark-drive-upload.md) 上传本地文件到云空间（云盘/云存储）并获取 `file_token`。
    - **生成妙记**：获取到 `file_token` 后，调用 [`lark-cli minutes +upload`](references/lark-minutes-upload.md) 将文件转换为妙记并获取 `minute_url` 链接。
-   - **继续获取纪要 / 逐字稿（按需）**：如果用户目标不是只要妙记链接，而是要纪要、逐字稿、总结、待办或章节，则从 `minute_url` 中提取 `minute_token`，再调用 [`lark-cli vc +notes --minute-tokens`](../lark-vc/references/lark-vc-notes.md) 获取对应产物。
+   - **继续获取纪要 / 逐字稿（按需）**：如果用户目标不是只要妙记链接，而是要纪要、逐字稿、总结、待办或章节，则从 `minute_url` 中提取 `minute_token`，再调用 [`lark-cli minutes +detail --minute-tokens`](references/lark-minutes-detail.md) 获取对应产物。
 
 > **注意**：必须先获取飞书云空间（云盘/云存储）的 `file_token` 才能进行转换。
 >
-> **不要误走本地转写工具**：当用户目标是把本地音视频文件转成纪要、逐字稿、文字稿、撰写文字时，不要改用 `ffmpeg`、`whisper` 或其他本地 ASR/转码命令；标准路径就是 `drive +upload -> minutes +upload -> vc +notes --minute-tokens`。
+> **不要误走本地转写工具**：当用户目标是把本地音视频文件转成纪要、逐字稿、文字稿、撰写文字时，不要改用 `ffmpeg`、`whisper` 或其他本地 ASR/转码命令；标准路径就是 `drive +upload -> minutes +upload -> minutes +detail --minute-tokens`。
 
-### 6. 编辑妙记的 AI 待办与 AI 总结（写入）
+### 5. 编辑妙记的 AI 待办与 AI 总结（写入）
 
 当用户要在**某条妙记内**操作 AI 待办或 AI 总结时使用本节。**不是**飞书任务（Task）清单里的待办。
 
@@ -141,73 +118,58 @@ lark-cli minutes +todo --minute-token <token> --as user --todos '[
 ]'
 ```
 
-**更新 / 删除前**：先用 `vc +notes --minute-tokens <token>` 读取 `todos[].todo_id`（按 `content` 匹配目标条目；列表顺序不保证稳定，**不要**用"第 2 条"代替 `todo_id`）。
+**更新 / 删除前**：先用 `minutes +detail --minute-tokens <token> --todo` 读取 `todos[].todo_id`（按 `content` 匹配目标条目；列表顺序不保证稳定，**不要**用"第 2 条"代替 `todo_id`）。
 
 **无编辑权限**：若 CLI 返回 `error.type=no_edit_permission`，表示对**这条妙记**没有编辑权，应请所有者授权；**不要**误走 `auth login --scope`。
 
-**逐字稿关键词替换无命中**：`minutes +word-replace` 时，若 CLI 返回 `error.type=words_not_found`，表示传入的 `source_word` 在该妙记逐字稿中**一个都没匹配到**，未做任何替换。这是**参数问题不是权限问题**：先用 `vc +notes --minute-tokens <token>` 读取当前逐字稿，核对 `source_word` 的精确写法与大小写后重试。
+**逐字稿关键词替换无命中**：`minutes +word-replace` 时，若 CLI 返回 `error.type=words_not_found`，表示传入的 `source_word` 在该妙记逐字稿中**一个都没匹配到**，未做任何替换。这是**参数问题不是权限问题**：先用 `minutes +detail --minute-tokens <token> --transcript` 读取当前逐字稿，核对 `source_word` 的精确写法与大小写后重试。
 
 **替换 AI 总结全文**：见 [minutes +summary](references/lark-minutes-summary.md)。
 
 > 使用 `+todo` 前必须阅读 [references/lark-minutes-todo.md](references/lark-minutes-todo.md)；使用 `+summary` 前必须阅读 [references/lark-minutes-summary.md](references/lark-minutes-summary.md)。
 
-## 资源关系
+### 7. 替换妙记逐字稿说话人
 
-```text
-Minutes (妙记) ← minute_token 标识
-├── Metadata (标题、封面、时长、owner、url) → minutes minutes get
-└── MediaFile (音频/视频文件) → minutes +download
+当用户要把妙记里某说话人的发言改绑到另一位飞书用户时使用。
+
+**触发信号**：「替换说话人」「把 A 的发言改成 B」「说话人识别错了」「把外部说话人改成飞书用户」等。
+
+**Agent 必读流程**（详见 [minutes +speaker-replace](references/lark-minutes-speaker-replace.md)）：
+
+1. 确认 `minute_token`。
+2. **先**用 `lark-cli api GET "/open-apis/minutes/v1/minutes/<token>/transcript/speakerlist"` 查说话人列表（内部 HTTP，无 shortcut、无公开 OpenAPI 文档页）。
+3. 根据用户描述的原说话人展示名，在返回的 `data.speakers[]` 中匹配 `name` → 得到 `speaker_id`；同名多人时结合 `vc +notes` 逐字稿请用户确认，**不要擅自挑选**。
+4. 新说话人姓名用 [lark-contact](../lark-contact/SKILL.md) 解析为 `ou_` open_id。
+5. 调用 `minutes +speaker-replace`，**`--from-speaker-id` 只传步骤 3 的 `speaker_id`，禁止传展示名**。
+
+## 行为规则
+
+### 1. `+detail` 必须显式声明产物 flag
+
+不传 `--summary` / `--todo` / `--chapter` / `--keyword` / `--transcript` 时只返回基础信息（含顶层 `note_id`），AI 产物字段一律不返回。即使产物为空也会返回空值字段，便于程序化处理。
+
+```bash
+# 拿全产物
+lark-cli minutes +detail --minute-tokens <token> --summary --todo --chapter --keyword --transcript
 ```
 
-> **能力边界**：`minutes` 负责 **搜索妙记、查看基础元信息、下载/上传音视频、编辑妙记 AI 待办与 AI 总结、重命名、逐字稿说话人/关键词替换**。
->
-> **路由规则**：
->
-> - 用户说"妙记列表 / 搜索妙记 / 某个关键词的妙记" → `minutes +search`
-> - 用户只是想看"我的妙记 / 某段时间内的妙记 / 妙记列表"，不要先走 [lark-vc](../lark-vc/SKILL.md)，而应直接使用本 skill
-> - 用户如果同时提到"会议 / 会 / 开会 / 某场会"，即使也提到了"妙记"，也应优先走 [lark-vc](../lark-vc/SKILL.md) 先定位会议，再通过 [vc +recording](../lark-vc/references/lark-vc-recording.md) 获取 `minute_token`
-> - 用户如果要的是妙记基础信息，拿到 `minute_token` 后用 `minutes minutes get`；用户如果要**读取**逐字稿、文字稿、撰写文字、总结、待办、章节，再走 `vc +notes --minute-tokens`
-> - “我的妙记”“参与的妙记”等自然语言映射细则，以 [minutes +search](references/lark-minutes-search.md) 为准
-> - 结果有多页时，使用 `page_token` 持续翻页，直到确认没有更多结果
-> - `minutes +search` 单次最多返回 `200` 条；结果总数没有固定上限
-> - 用户说"这个妙记的标题 / 时长 / 封面 / 链接" → `minutes minutes get`
-> - 用户说"下载这个妙记的视频 / 音频 / 媒体文件" → `minutes +download`
-> - 用户要**读取**"这个妙记的逐字稿 / 文字稿 / 撰写文字 / 总结 / 待办 / 章节" → [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md)
-> - 用户要在**妙记内新建 / 修改 / 删除 AI 待办**（含「妙记里加待办」「任务1 已完成」等）→ [`minutes +todo`](references/lark-minutes-todo.md)，**禁止**走 lark-task
-> - 用户要**替换妙记 AI 总结全文** → [`minutes +summary`](references/lark-minutes-summary.md)
-> - 用户说"通过文件生成妙记 / 把音视频转妙记" → 先上传获取 `file_token`，然后使用 `minutes +upload`
-> - 用户说"把音视频文件转成纪要 / 逐字稿 / 文字稿 / 撰写文字 / 总结 / 待办 / 章节" → 先上传获取 `file_token`，调用 `minutes +upload` 生成 `minute_url`，再提取 `minute_token` 走 `vc +notes --minute-tokens`
-> - 用户说"重命名妙记 / 改妙记标题 / 修改妙记名字" → `minutes +update`
-> - 用户说"替换说话人 / 把 A 的发言改成 B / 重新归属发言人" → `minutes +speaker-replace`
-> - 用户说"批量替换逐字稿关键词" → `minutes +word-replace`
->
-> **Note 域边界（禁止规则）**：`minute_token` 是妙记文件标识，**不是** `note_id`。
-> - 不要把 `minute_token` 传给 `note +detail` 或 `note +transcript`。
-> - 已有 `minute_token` 且要读取纪要产物时，先走 [lark-vc](../lark-vc/SKILL.md)；只有自然语言纪要标题时不要从 Minutes 反查。
+### 2. "提炼 / 总结"必须基于 Transcript，不要照搬 AI 总结
 
-## Shortcuts（推荐优先使用）
+AI 总结是模型对会议的二次压缩，可能遗漏争论过程和隐含决策。用户要求"提炼"或"重新总结"时，期望基于原始发言独立分析，而非搬运 AI 产物。**优先 `--transcript`，再独立写结论**。
 
-Shortcut 是对常用操作的高级封装（`lark-cli minutes +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+### 3. 从妙记反查纪要：不绕 lark-vc
 
-| Shortcut                                           | 说明                                                              |
-| -------------------------------------------------- | --------------------------------------------------------------- |
-| [`+search`](references/lark-minutes-search.md)     | Search minutes by keyword, owners, participants, and time range |
-| [`+download`](references/lark-minutes-download.md) | Download audio/video media file of a minute                     |
-| [`+upload`](references/lark-minutes-upload.md)     | Upload a media file token to generate a minute                  |
-| [`+update`](references/lark-minutes-update.md)     | Update a minute's title                                         |
-| [`+speaker-replace`](references/lark-minutes-speaker-replace.md) | Replace a speaker in a minute's transcript (rebind from one user to another) |
-| [`+summary`](references/lark-minutes-summary.md) | Replace the full AI summary text of a minute |
-| [`+todo`](references/lark-minutes-todo.md) | Add, update, or delete **AI todo(s) inside a minute** (single or batch via `--todos`; not Feishu Task) |
+`minutes +detail` 顶层直接返回 `note_id`（仅在该妙记关联纪要时存在）。不需要绕回 [lark-vc](../lark-vc/SKILL.md)，直接：
 
-- 使用 `+search` 命令时，必须阅读 [references/lark-minutes-search.md](references/lark-minutes-search.md)，了解搜索参数和返回值结构。
-- 使用 `+download` 命令时，必须阅读 [references/lark-minutes-download.md](references/lark-minutes-download.md)，了解下载参数和返回值结构。
-- 使用 `+upload` 命令时，必须阅读 [references/lark-minutes-upload.md](references/lark-minutes-upload.md)，了解生成参数和返回值结构。
-- 使用 `+update` 命令时，必须阅读 [references/lark-minutes-update.md](references/lark-minutes-update.md)，了解修改参数和返回值结构。
-- 使用 `+speaker-replace` 命令时，必须阅读 [references/lark-minutes-speaker-replace.md](references/lark-minutes-speaker-replace.md)，了解参数和限制（仅支持用户 ID，不支持姓名）。
-- 使用 `+summary` 命令时，必须阅读 [references/lark-minutes-summary.md](references/lark-minutes-summary.md)，了解全文替换参数。
-- 使用 `+todo` 命令时，必须阅读 [references/lark-minutes-todo.md](references/lark-minutes-todo.md)，了解单条与 `--todos` 批量模式；**不要**用 lark-task。
+```bash
+# 1) 取 note_id（顶层 .minutes[0].note_id）
+lark-cli minutes +detail --minute-tokens <minute_token> --format json
+# 2) 用上一步拿到的 note_id 读纪要 token
+lark-cli note +detail --note-id <note_id>   # 拿 note_doc_token / verbatim_doc_token / shared_doc_tokens
+```
+
+顶层无 `note_id` 字段即代表无关联纪要，到此为止——不要继续尝试用 `minute_token` 当 `note_id`。
 
-<!-- AUTO-GENERATED-START — gen-skills.py 管理，勿手动编辑 -->
 
 ## API Resources
 
@@ -223,7 +185,8 @@ lark-cli minutes <resource> <method> [flags]
 
 ## 不在本 skill 范围
 
-- 已有 `minute_token` 的纪要/逐字稿/总结/待办/章节内容获取 → [lark-vc](../lark-vc/SKILL.md)（`vc +notes --minute-tokens`）
-- 只有自然语言纪要标题的逐字稿查询 → 文档搜索 / Docx 正文读取；有显式 `vc-node-id` 才进入 [lark-note](../lark-note/SKILL.md)
-- 搜索历史会议记录 → [lark-vc](../lark-vc/SKILL.md)
-- 查询未来的会议日程 → [lark-calendar](../lark-calendar/SKILL.md)
+- 搜索历史会议记录、查参会人快照 → [lark-vc](../lark-vc/SKILL.md)
+- 未来日程 / 日历查询 → [lark-calendar](../lark-calendar/SKILL.md)
+- 已知 `note_id` 直接读纪要详情 → [lark-note](../lark-note/SKILL.md)
+- 飞书任务清单（个人 Todo / 共享清单） → [lark-task](../lark-task/SKILL.md)
+- 只有自然语言纪要标题、没有 `minute_token` / 妙记 URL / 本地音视频时定位逐字稿 → 文档搜索（[lark-drive](../lark-drive/SKILL.md) / [lark-doc](../lark-doc/SKILL.md)）

skills/lark-minutes/references/lark-minutes-detail.md

@@ -0,0 +1,62 @@
+
+# minutes +detail
+
+通过 `minute_token` 查询妙记详情，按需获取 AI 产物（总结/待办/章节/逐字稿/关键词）。只读。
+
+> `--summary` / `--todo` / `--chapter` / `--keyword` / `--transcript` 至少一个；不传任何产物 flag 时只返回基础信息（如 `title`），AI 产物字段都不会出现。一次性获取所有产物：`--summary --todo --chapter --keyword --transcript`。
+
+## 命令
+
+```bash
+# 仅基础信息
+lark-cli minutes +detail --minute-tokens obcxxxxxxxxxx
+
+# 批量（逗号分隔，最多 50 个）
+lark-cli minutes +detail --minute-tokens obcxxx,obcyyy --summary --todo
+
+# 全产物
+lark-cli minutes +detail --minute-tokens obcxxx --summary --todo --chapter --keyword --transcript
+
+# 仅逐字稿，覆盖已有文件，指定输出目录
+lark-cli minutes +detail --minute-tokens obcxxx --transcript --overwrite --output-dir ./out
+```
+
+## 输出
+
+`minutes` 数组每条含 `minute_token`、`title`、`note_id`、`artifacts`。`note_id` 仅在该妙记关联了会议纪要时返回，可直接传给 [`note +detail`](../../lark-note/references/lark-note-detail.md) 拿纪要文档 token，无需再绕回 `vc +detail`。`artifacts` 中**只包含本次请求的产物**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `artifacts.summary` | string | AI 总结。 |
+| `artifacts.todos` | array | 待办事项列表。 |
+| `artifacts.chapters` | array | 章节列表。 |
+| `artifacts.keywords` | array | 关键词列表。 |
+| `artifacts.transcript_file` | string | 逐字稿本地文件路径。 |
+
+逐字稿默认落地 `./minutes/{minute_token}/transcript.txt`，与 `minutes +download` 同目录便于聚合。指定 `--output-dir <dir>` 时改写到 `<dir>/artifact-{title}-{minute_token}/transcript.txt`。
+
+## minute_token 来源
+
+| 来源 | 取值字段 |
+|------|---------|
+| 妙记 URL `https://*.feishu.cn/minutes/obcxxx` | 截路径最后一段 `obcxxx` |
+| `vc +detail --meeting-ids` | `minute_token` |
+| `vc +recording --meeting-ids` | `minute_token` |
+| `minutes +search` | `minute_token` |
+
+## 典型链路：从 minute_token 拿纪要文档 token
+
+只持有 `minute_token`（如妙记 URL 入口），又想拿 AI 智能纪要 / 逐字稿文档时：
+
+```bash
+# 1. 取妙记关联的 note_id，没有关联会议纪要则为空
+lark-cli minutes +detail --minute-tokens <minute_token>
+
+# 2. 用 note_id 拿 note_doc_token / verbatim_doc_token / shared_doc_tokens
+lark-cli note +detail --note-id <note_id>
+
+# 3. 读纪要 / 逐字稿正文
+lark-cli docs +fetch --api-version v2 --doc <note_doc_token> --doc-format markdown
+```
+
+> `minute_token` 不要直接传给 `note +detail`：必须先用本命令拿到 `note_id` 再调用 `note +detail`。

skills/lark-minutes/references/lark-minutes-download.md

@@ -43,7 +43,7 @@ lark-cli minutes +download --minute-tokens obcnxxxxxxxxxxxxxxxxxxxx --dry-run
 | `--url-only` | 否 | 仅返回下载链接，不下载文件 |
 | `--dry-run` | 否 | 预览 API 调用，不执行 |
 
-> **默认落点**：未指定 `--output` / `--output-dir` 时，文件落到 `./minutes/{minute_token}/<server-filename>`。文件名沿用服务端 Content-Disposition / Content-Type 推断，Agent 可从 `saved_path` 字段读取实际路径。同一 minute_token 的录像和 `vc +notes` 的逐字稿默认会落在**同一目录**下，方便聚合。
+> **默认落点**：未指定 `--output` / `--output-dir` 时，文件落到 `./minutes/{minute_token}/<server-filename>`。文件名沿用服务端 Content-Disposition / Content-Type 推断，Agent 可从 `saved_path` 字段读取实际路径。同一 minute_token 的录像和 `minutes +detail` 的逐字稿默认会落在**同一目录**下，方便聚合。
 
 ## 核心约束
 
@@ -85,7 +85,7 @@ API 限流 5 次/秒，批量下载时需注意控制频率。
 | 字段 | 说明 |
 |------|------|
 | `minute_token` | 妙记 Token（用于 Agent 索引） |
-| `artifact_type` | 固定为 `"recording"`（与 `vc +notes` 的 `"transcript"` 区分） |
+| `artifact_type` | 固定为 `"recording"`（与 `minutes +detail` 的 `"transcript"` 区分） |
 | `saved_path` | 文件保存的本地路径（绝对路径） |
 | `size_bytes` | 文件大小（字节） |
 
@@ -125,13 +125,13 @@ API 限流 5 次/秒，批量下载时需注意控制频率。
 ## 提示
 
 - 音视频文件可能较大，下载无固定超时限制（由用户 Ctrl+C 控制取消）。
-- 默认落点 `./minutes/{minute_token}/` 与 `vc +notes` 的逐字稿共享同一目录，方便 Agent 聚合同一会议的所有产物。
+- 默认落点 `./minutes/{minute_token}/` 与 `minutes +detail` 的逐字稿共享同一目录，方便 Agent 聚合同一会议的所有产物。
 - 单 token 模式下 `--output` 若传入已存在目录（如 `--output ./existing-dir`），等价于 `--output-dir`，文件落入该目录（cp 语义）。
 - 批量模式下 `--output` 不接受已存在的文件路径（会报错），应改用 `--output-dir`。
-- 如需获取妙记的纪要内容（逐字稿、AI 总结等），请使用 [vc +notes](../../lark-vc/references/lark-vc-notes.md)。
+- 如需获取妙记的纪要内容（逐字稿、AI 总结等），请使用 [minutes +detail](lark-minutes-detail.md)。
 
 ## 参考
 
 - [lark-minutes](../SKILL.md) — 妙记全部命令
-- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) — 会议纪要查询
+- [lark-minutes-detail](lark-minutes-detail.md) — 妙记详情与 AI 产物查询
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-minutes/references/lark-minutes-search.md

@@ -129,8 +129,6 @@ CLI 会先按输入的本地日历日语义解析，再标准化为 RFC3339 时
 2. `vc +recording` 获取 `minute_token`
 3. `minutes minutes get` 查询妙记基础信息
 
-不要为了查"妙记信息"直接走 `vc +notes --meeting-ids`。`vc +notes` 只适用于逐字稿、总结、待办、章节等纪要内容。
-
 <br />
 
 ## 时间格式
@@ -145,14 +143,14 @@ CLI 会先按输入的本地日历日语义解析，再标准化为 RFC3339 时
 
 ## 输出结果
 
-- 默认输出包含 `items`、`total`、`has_more` 和 `page_token`。
+- 默认输出包含 `items`、`has_more` 和 `page_token`。
 
 ## Pagination (`has_more` / `page_token`)
 
 - 当结果中返回 `has_more=true` 时，说明还有更多页可继续获取。
 - 继续翻页时，使用响应中的 `page_token` 搭配 `--page-token` 发起下一次查询。
 - 不要假设调大 `--page-size` 就能拿全结果；分页遍历时应以 `has_more` 和 `page_token` 为准。
-- `total` 数量小于 50 时，自动分页获取所有结果；`total` 数量大于 50 时，向用户确认是否获取全部结果。
+- 当 `has_more=true` 时，逐页累计已读取的 `items` 数：累计不到 50 条之前可自动继续翻页；超过 50 条后应停下来向用户确认是否获取全部结果。
 
 ```bash
 # First page
@@ -173,8 +171,8 @@ lark-cli minutes +search --query "预算复盘" --page-size 20 --page-token '<PA
 # 首先查询妙记元信息（标题、时长、封面） → 用本 skill
 lark-cli minutes minutes get --params '{"minute_token": "obcn***************"}'
 
-# 查妙记关联的纪要产物：逐字稿、总结、待办、章节等 → 用 lark-cli vc +notes
-lark-cli vc +notes --minute-tokens obcn_EXAMPLE_TOKEN
+# 查妙记关联的产物(--summary --todo --chapter --keyword --transcript 按需返回)
+lark-cli minutes +detail --minute-tokens <minute_token> --summary
 ```
 
 ## 常见错误与排查
@@ -192,7 +190,7 @@ lark-cli vc +notes --minute-tokens obcn_EXAMPLE_TOKEN
 - 当用户说“我的妙记”时，优先理解为 `--owner-ids me`。
 - 当用户说“我参与的妙记”“我参加过的妙记”时，默认理解为 `--owner-ids me` 与 `--participant-ids me` 两次查询后的并集。
 - 当用户明确说“仅我参与但不是我拥有”时，才优先理解为 `--participant-ids me`。
-- 当用户同时提到“会议 / 会 / 开会 / 某场会”和“妙记”时，优先先定位会议；如果要的是妙记信息，走 `vc +recording` → `minutes minutes get`，只有要纪要内容时才走 `vc +notes --minute-tokens`。
+- 当用户同时提到“会议 / 会 / 开会 / 某场会”和“妙记”时，优先先定位会议；如果要的是妙记信息，走 `vc +recording` 获取 `minute_token` → `minutes minutes get`，只有要妙记产物内容时才走 `minutes +detail --minute-tokens`。
 - 必须使用 `--format json` 输出，你更加擅长解析 JSON 数据。
 - 排查参数与请求结构时优先使用 `--dry-run`。
 - 搜索的时间范围最大为 1 个月，如果需要搜索更长时间范围的妙记，需要拆分为多次时间范围为一个月查询。
@@ -200,7 +198,7 @@ lark-cli vc +notes --minute-tokens obcn_EXAMPLE_TOKEN
 ## 参考
 
 - [lark-minutes](../SKILL.md) -- 妙记相关命令
-- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) -- 基于 `minute_token` 获取逐字稿、总结、待办、章节等产物
+- [lark-minutes-detail](lark-minutes-detail.md) -- 基于 `minute_token` 获取逐字稿、总结、待办、章节等产物
 - [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
 - [lark-vc](../../lark-vc/SKILL.md) -- 视频会议全部命令
 

skills/lark-minutes/references/lark-minutes-speaker-replace.md

@@ -2,7 +2,7 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-替换妙记逐字稿中的说话人身份：把妙记逐字稿里"原说话人"对应的所有发言段，重新归属到"新说话人"。常用于解决妙记自动识别错说话人，或需要手工把某段语音绑定到正确用户的场景。
+替换妙记逐字稿中的说话人身份：把妙记逐字稿里"原说话人"对应的所有发言段，重新归属到"新说话人"。常用于解决妙记自动识别错说话人，或需要把外部/非飞书说话人改绑到正确飞书用户的场景。
 
 本 skill 对应 shortcut：`lark-cli minutes +speaker-replace`。
 
@@ -10,15 +10,60 @@
 
 - "把这条妙记里 A 的发言改成 B"
 - "妙记说话人识别错了，帮我把张三的部分换成李四"
+- "把妙记里外部说话人 / 非飞书说话人的发言改成某个飞书用户"
 - "妙记说话人修改 / 替换 / 重新归属"
-- "改一下妙记的说话人"
+
+## 完整工作流
+
+识别到「修改妙记说话人」需求后，**必须**按以下顺序执行；**禁止**把展示名直接传给 `--from-speaker-id`。
+
+1. **确认 `minute_token`**
+   - 从妙记 URL、搜索或 VC 链路取得 `minute_token`。
+
+2. **查说话人列表（必须先做）**
+   - 用 **`lark-cli api`** 直接调用内部 HTTP 接口：
+     ```bash
+     lark-cli api GET "/open-apis/minutes/v1/minutes/<minute_token>/transcript/speakerlist" --as user
+     ```
+   - 返回 `data.speakers[]`，每项含 `speaker_id`（不透明 id）与 `name`（逐字稿展示名）。示例：
+     ```json
+     {
+       "data": {
+         "speakers": [
+           {"speaker_id": "ENCRYPTED_TOKEN_ABC", "name": "说话人1"},
+           {"speaker_id": "ENCRYPTED_TOKEN_DEF", "name": "说话人2"}
+         ]
+       }
+     }
+     ```
+
+3. **解析 `--from-speaker-id`**
+   - 根据用户描述的原说话人（展示名，如「说话人1」「张三」），在 `speakers[]` 里按 `name` **精确匹配**，取对应的 **`speaker_id`** 作为 `--from-speaker-id` 的值。
+   - **`--from-speaker-id` 只传 `speaker_id`，不传展示名。**
+   - 若同名有多条（`name` 相同、`speaker_id` 不同）：**不要擅自挑选**。可结合 [`vc +notes --minute-tokens`](../../lark-vc/references/lark-vc-notes.md) 对照各人发言内容，请用户确认后再用精确的 `speaker_id`。
+   - 若列表中无匹配展示名：告知用户并核对拼写，或请用户在妙记页面确认标签。
+
+4. **解析 `--to-user-id`**
+   - 新说话人必须是 `ou_` 开头的 open_id。用户只给姓名时，先用 [lark-contact](../../lark-contact/SKILL.md) 解析。
+
+5. **执行替换**
+   ```bash
+   lark-cli minutes +speaker-replace \
+     --minute-token obcnxxxxxxxxxxxxxxxxxxxx \
+     --from-speaker-id ENCRYPTED_TOKEN_ABC \
+     --to-user-id ou_new_speaker_open_id
+   ```
 
 ## 命令示例
 
 ```bash
+# 1. 先查列表（裸调 HTTP）
+lark-cli api GET "/open-apis/minutes/v1/minutes/obcnxxxxxxxxxxxxxxxxxxxx/transcript/speakerlist" --as user
+
+# 2. 再替换（from-speaker-id 来自上一步的 speaker_id）
 lark-cli minutes +speaker-replace \
   --minute-token obcnxxxxxxxxxxxxxxxxxxxx \
-  --from-user-id ou_old_speaker_open_id \
+  --from-speaker-id ENCRYPTED_TOKEN_ABC \
   --to-user-id ou_new_speaker_open_id
 ```
 
@@ -27,21 +72,33 @@ lark-cli minutes +speaker-replace \
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--minute-token <token>` | 是 | 妙记的唯一标识，可从妙记 URL 末尾路径提取 |
-| `--from-user-id <ou_xxx>` | 是 | 被替换的原说话人，**必须是 `ou_` 开头的 open_id**，不支持用户名 |
+| `--from-speaker-id <id>` | 是 | 被替换的原说话人 **`speaker_id`**（来自 speakerlist API 的 `data.speakers[].speaker_id`） |
 | `--to-user-id <ou_xxx>` | 是 | 新的说话人，**必须是 `ou_` 开头的 open_id**，不支持用户名 |
 
-> **重要**：`--from-user-id` 和 `--to-user-id` 仅支持 `ou_` 开头的用户 ID，**不支持直接传姓名**。如果用户只给了姓名，请先用 [lark-contact](../../lark-contact/SKILL.md) 把姓名解析成 `open_id`，再调用本命令。
+## 核心约束
+
+### 1. 必须先查 speakerlist，再替换
+
+Agent 必须先 `lark-cli api GET .../speakerlist`，再 `+speaker-replace`；`--from-speaker-id` 只接受 `speaker_id`。
+
+### 2. 新说话人必须是 open_id
+
+`--to-user-id` 仅支持 `ou_` 开头的 open_id，**不支持直接传姓名**；如果用户只给了姓名，请先用 [lark-contact](../../lark-contact/SKILL.md) 把姓名解析成 `open_id`。
+
+### 3. 历史参数
+
+存在一个隐藏的历史参数 `--from-user-id`（飞书说话人的 open_id），仅为向后兼容保留；新流程请一律使用 `--from-speaker-id` + `speaker_id`。
 
 ## 认证与权限
 
-- 所需 scope：`minutes:minutes:update`。
+- 所需 scope：`minutes:minutes:readonly`（内部解析说话人）、`minutes:minutes:update`（执行替换）。
 
 ## 输出结果
 
 | 字段 | 说明 |
 |------|------|
 | `minute_token` | 被修改的妙记 Token，与输入的 `--minute-token` 一致 |
-| `from_user_id` | 被替换的原说话人 open_id，与输入的 `--from-user-id` 一致；必须是妙记逐字稿中已存在的说话人 |
+| `from_speaker_id` | 实际用于替换的不透明说话人标识 |
 | `to_user_id` | 替换后的新说话人 open_id，与输入的 `--to-user-id` 一致 |
 
 ## 参考

skills/lark-minutes/references/lark-minutes-summary.md

@@ -40,7 +40,7 @@ lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @sum
 
 ### 1. 先读后写
 
-替换前建议先用 `lark-cli vc +notes --minute-tokens <token>` 读取当前总结，确认 `minute_token` 与待替换内容无误。
+替换前建议先用 `lark-cli minutes +detail --minute-tokens <token> --summary` 读取当前总结，确认 `minute_token` 与待替换内容无误。
 
 ### 2. Markdown 展示说明
 
@@ -104,7 +104,7 @@ lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @sum
 |------|---------|
 | 妙记 URL | 从 URL 末尾提取，如 `https://sample.feishu.cn/minutes/obcnxxxxxxxxxxxxxxxxxxxx` |
 | 妙记搜索 | `lark-cli minutes +search --query "关键词"` |
-| 会议产物查询 | `lark-cli vc +notes --minute-tokens <token>` |
+| 会议产物查询 | `lark-cli vc +detail --meeting-ids <id>` 或 `vc +recording`, 拿到 `minute_token`, 然后走 `minutes +detail` |
 
 ## 常见错误与排查
 
@@ -118,5 +118,5 @@ lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @sum
 
 - [lark-minutes](../SKILL.md) — 妙记全部命令
 - [minutes +todo](lark-minutes-todo.md) — 替换待办项
-- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) — 读取总结、待办等 AI 产物
+- [minutes +detail](lark-minutes-detail.md) — 读取总结、待办等 AI 产物
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-minutes/references/lark-minutes-todo.md

@@ -94,7 +94,7 @@ lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add -
 
 ### 1. 先读后写，待办 id 如何获取
 
-更新 / 删除前先用 `lark-cli vc +notes --minute-tokens <token>` 读取当前待办。返回的每条待办带 `todo_id` 字段。
+更新 / 删除前先用 `lark-cli minutes +detail --minute-tokens <token> --todo` 读取当前待办。返回的每条待办带 `todo_id` 字段。
 
 > 待办 id 仅用于程序内部定位，不必展示给用户。
 
@@ -134,5 +134,5 @@ lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add -
 
 - [lark-minutes](../SKILL.md)
 - [minutes +summary](lark-minutes-summary.md)
-- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md)
+- [minutes +detail](lark-minutes-detail.md)
 - [lark-shared](../../lark-shared/SKILL.md)