feat: minute wait

feat: remove reference lark-sharded skill

docs: clarify calendar write feedback

docs: split calendar scheduling workflow

docs: tighten calendar skill references

docs: annotate +freebusy scope to avoid unnecessary reads in scheduling flow

When users express "find free time + create event" intent, AI would
previously read freebusy.md before entering the scheduling workflow.
Adding a scope note to the shortcut table directs AI to use +suggestion
instead, reducing token consumption.

feat: support calendar +get

fix: optimize calendar skill

fix: optimize shortcuts and meta api

fix: optimize skill

.gitignore

@@ -27,6 +27,9 @@ Thumbs.db
 # Go
 docs/ref
 docs/
+!tests/cli_e2e/docs/
+!tests/cli_e2e/docs/*.go
+!tests/cli_e2e/docs/*.md
 vendor/
 
 

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.65] - 2026-07-03
+
+### Features
+
+- **doc**: Add `+history-list`, `+history-revert`, and `+history-revert-status` shortcuts for document version history (#1612)
+
+### Bug Fixes
+
+- **minutes**: `+speaker-replace` no longer refetches the speaker list — `--from-speaker-id` is passed through as-is (#1731)
+
+### Documentation
+
+- **drive**: Document 30-char query limit for `+search` (#1560)
+- **doc**: Add mindnote guidance to lark-doc skill (#1581)
+- **doc**: Sync lark-doc skill content from online-doc (#1701)
+
 ## [v1.0.64] - 2026-07-02
 
 ### Features
@@ -1355,6 +1371,7 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.65]: https://github.com/larksuite/cli/releases/tag/v1.0.65
 [v1.0.64]: https://github.com/larksuite/cli/releases/tag/v1.0.64
 [v1.0.62]: https://github.com/larksuite/cli/releases/tag/v1.0.62
 [v1.0.61]: https://github.com/larksuite/cli/releases/tag/v1.0.61

README.md

@@ -233,6 +233,24 @@ lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_i
 --format csv       # Comma-separated values
 ```
 
+### JSON Output Contract
+
+With `--format json` (the default), success and error envelopes are distinct.
+
+Success goes to **stdout**, exit code `0`:
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+Errors go to **stderr**, non-zero exit code:
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
+```
+
+To check whether a command succeeded, test `ok == true` (or the exit code) — **not** `code == 0`. Unlike raw OpenAPI responses (`{"code": 0, "msg": "ok", ...}`), the success envelope carries no `code` or `msg` field; `code` appears only inside `error` as the upstream OpenAPI code. See [errs/ERROR_CONTRACT.md](errs/ERROR_CONTRACT.md) for the full error taxonomy.
+
 ### Pagination
 
 ```bash

README.zh.md

@@ -234,6 +234,24 @@ lark-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"chat_i
 --format csv       # 逗号分隔值
 ```
 
+### JSON 输出契约
+
+`--format json`（默认）下，成功与错误的信封结构不同。
+
+成功信封写入 **stdout**，退出码 0：
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+错误信封写入 **stderr**，退出码非 0：
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
+```
+
+判断命令是否成功，请检查 `ok == true`（或进程退出码），**不要用 `code == 0`**。与原始 OpenAPI 响应（`{"code": 0, "msg": "ok", ...}`）不同，成功信封没有 `code` 和 `msg` 字段；`code` 只出现在错误信封的 `error` 内，含义是上游 OpenAPI 的 numeric code。完整错误分类见 [errs/ERROR_CONTRACT.md](errs/ERROR_CONTRACT.md)。
+
 ### 分页
 
 ```bash

cmd/api/api_test.go

@@ -20,13 +20,28 @@ import (
 	"github.com/spf13/cobra"
 )
 
+func newTestApiCmd(f *cmdutil.Factory, runF func(*APIOptions) error) *cobra.Command {
+	cmd := NewCmdApi(f, runF)
+	cmd.SilenceErrors = true
+	cmd.SilenceUsage = true
+	return cmd
+}
+
+func newTestRootCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:           "lark-cli",
+		SilenceErrors: true,
+		SilenceUsage:  true,
+	}
+}
+
 func TestApiCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -54,7 +69,7 @@ func TestApiCmd_DryRun(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--dry-run"})
 	err := cmd.Execute()
 	if err != nil {
@@ -77,7 +92,7 @@ func TestApiCmd_NullParamsWithPageSize(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--params", "null", "--page-size", "50", "--as", "bot", "--dry-run"})
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("--params null with --page-size should not error, got: %v", err)
@@ -98,7 +113,7 @@ func TestApiCmd_BotMode(t *testing.T) {
 		Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{"result": "success"}},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot"})
 	err := cmd.Execute()
 	if err != nil {
@@ -125,7 +140,7 @@ func TestApiCmd_MissingArgs(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET"}) // missing path
 	err := cmd.Execute()
 	if err == nil {
@@ -138,7 +153,7 @@ func TestApiCmd_InvalidParamsJSON(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--params", "{bad"})
 	err := cmd.Execute()
 	if err == nil {
@@ -151,7 +166,7 @@ func TestApiValidArgsFunction(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	fn := cmd.ValidArgsFunction
 
 	tests := []struct {
@@ -217,7 +232,7 @@ func TestNewCmdApi_StrictModeHidesAsFlag(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu, SupportedIdentities: 2,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	flag := cmd.Flags().Lookup("as")
 	if flag == nil {
 		t.Fatal("expected --as flag to be registered")
@@ -236,7 +251,7 @@ func TestApiCmd_PageLimitDefault(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -255,7 +270,7 @@ func TestApiCmd_ParamsAndDataBothStdinConflict(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"POST", "/open-apis/test", "--as", "bot", "--params", "-", "--data", "-"})
 	err := cmd.Execute()
 	if err == nil {
@@ -272,7 +287,7 @@ func TestApiCmd_OutputAndPageAllConflict(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return apiRun(opts)
 	})
@@ -297,7 +312,7 @@ func TestApiCmd_BinaryResponse_AutoSave(t *testing.T) {
 		ContentType: "application/octet-stream",
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/drive/v1/files/xxx/download", "--as", "bot"})
 	err := cmd.Execute()
 	if err != nil {
@@ -328,7 +343,7 @@ func TestApiCmd_PageAll_NonBatchAPI_FallbackToJSON(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users/u123", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := cmd.Execute()
 	if err != nil {
@@ -368,7 +383,7 @@ func TestApiCmd_PageAll_NonBatchAPI_ErrorStillOutputsJSON(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/im/v1/chats/oc_xxx/announcement", "--as", "bot", "--page-all"})
 	err := cmd.Execute()
 	// Should return an error
@@ -409,7 +424,7 @@ func TestApiCmd_PageAll_BatchAPI_StreamsItems(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := cmd.Execute()
 	if err != nil {
@@ -448,7 +463,7 @@ func TestApiCmd_PageAll_StreamBusinessErrorDoesNotDumpJSON(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := cmd.Execute()
 	if err == nil {
@@ -483,7 +498,7 @@ func TestApiCmd_PageAll_BatchAPI_DefaultJSONEnvelope(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all"})
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -549,8 +564,8 @@ func TestApiCmd_PageAll_DefaultJSONRunsContentSafety(t *testing.T) {
 		},
 	})
 
-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(NewCmdApi(f, nil))
+	root := newTestRootCmd()
+	root.AddCommand(newTestApiCmd(f, nil))
 	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all"})
 	if err := root.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -600,8 +615,8 @@ func TestApiCmd_PageAll_StreamFormatRunsContentSafety(t *testing.T) {
 		},
 	})
 
-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(NewCmdApi(f, nil))
+	root := newTestRootCmd()
+	root.AddCommand(newTestApiCmd(f, nil))
 	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	if err := root.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -656,8 +671,8 @@ func TestApiCmd_PageAll_StreamFormatBlockSkipsBlockedPage(t *testing.T) {
 		},
 	})
 
-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(NewCmdApi(f, nil))
+	root := newTestRootCmd()
+	root.AddCommand(newTestApiCmd(f, nil))
 	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := root.Execute()
 	if err == nil {
@@ -721,7 +736,7 @@ func TestApiCmd_JqFlag_Parsing(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -741,7 +756,7 @@ func TestApiCmd_JqFlag_ShortForm(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -760,7 +775,7 @@ func TestApiCmd_JqAndOutputConflict(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", ".data", "--output", "file.bin"})
@@ -791,7 +806,7 @@ func TestApiCmd_JqFilter_AppliesExpression(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test/jq", "--as", "bot", "--jq", ".data.items[].name"})
 	err := cmd.Execute()
 	if err != nil {
@@ -812,7 +827,7 @@ func TestApiCmd_JqAndFormatConflict(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", ".data", "--format", "ndjson"})
@@ -830,7 +845,7 @@ func TestApiCmd_JqInvalidExpression(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", "invalid["})
@@ -859,7 +874,7 @@ func TestApiCmd_PageAll_WithJq(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--jq", ".data.items[].id"})
 	err := cmd.Execute()
 	if err != nil {
@@ -880,7 +895,7 @@ func TestApiCmd_MethodUppercase(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -899,7 +914,7 @@ func TestApiCmd_FileFlagParsing(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -917,7 +932,7 @@ func TestApiCmd_FileAndOutputConflict(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"POST", "/open-apis/test", "--as", "bot", "--file", "photo.jpg", "--output", "out.json"})
@@ -934,7 +949,7 @@ func TestApiCmd_FileWithGET(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--file", "photo.jpg"})
@@ -951,7 +966,7 @@ func TestApiCmd_FileStdinConflictWithData(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"POST", "/open-apis/test", "--as", "bot", "--file", "-", "--data", "-"})
@@ -974,7 +989,7 @@ func TestApiCmd_DryRunWithFile(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"POST", "/open-apis/im/v1/images", "--file", "image=" + tmpFile, "--data", `{"image_type":"message"}`, "--dry-run", "--as", "bot"})
 	err := cmd.Execute()
 	if err != nil {
@@ -1015,7 +1030,7 @@ func TestApiCmd_PermissionError_DerivesFirstClassFields(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/docx/v1/documents/test", "--as", "bot"})
 	err := cmd.Execute()
 	if err == nil {
@@ -1041,7 +1056,7 @@ func TestApiCmd_JsonFlag_Accepted(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})

errs/ERROR_CONTRACT.md

@@ -72,6 +72,28 @@ other category. `error.type` is `"policy"`, `error.subtype` is one of
 `challenge_required` / `access_denied`, and process exit is `6` via
 `CategoryPolicy`.
 
+### Success envelope (stdout)
+
+For contrast: success responses render to **stdout** as an
+`output.Envelope` (`internal/output/envelope.go`), exit code `0`:
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": { "guid": "e297d3d0-..." },
+  "meta": { "count": 1 }
+}
+```
+
+Consumers must branch on `ok` (or the process exit code). The success
+envelope has **no top-level `code` or `msg` field** — `code` exists only
+inside `error`, where it is the upstream numeric code (invariant 4).
+Wrappers that follow the raw OpenAPI convention and test `code == 0`
+will misclassify every successful call as a failure, which is
+especially dangerous around write commands (e.g. retrying a create that
+already succeeded).
+
 ## Categories
 
 | Category | When | Exit | Typed struct |

package.json

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

shortcuts/calendar/calendar_create.go

@@ -67,6 +67,26 @@ func parseAttendees(attendeesStr string, currentUserId string) ([]map[string]str
 	return attendees, nil
 }
 
+func attendeesIncludeRoom(attendees []map[string]string) bool {
+	for _, attendee := range attendees {
+		if attendee["type"] == "resource" || attendee["room_id"] != "" {
+			return true
+		}
+	}
+	return false
+}
+
+func guideApprovalRoomReasonError(err error, attendees []map[string]string) error {
+	if err == nil || !attendeesIncludeRoom(attendees) {
+		return err
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok || !strings.Contains(strings.ToLower(p.Hint), "approval_reason") {
+		return err
+	}
+	return withStepContext(err, "approval meeting rooms require attendees[].approval_reason; calendar +create does not expose this low-frequency field. Create the event with the raw API flow, then use `lark-cli calendar event.attendees create --as user` with attendees[].approval_reason for the room attendee.")
+}
+
 var CalendarCreate = common.Shortcut{
 	Service:     "calendar",
 	Command:     "+create",
@@ -225,6 +245,7 @@ var CalendarCreate = common.Shortcut{
 					"need_notification": true,
 				})
 			if err != nil {
+				err = guideApprovalRoomReasonError(err, attendees)
 				// Rollback: delete the event
 				_, rollbackErr := runtime.CallAPITyped("DELETE",
 					fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/%s", validate.EncodePathSegment(calendarId), validate.EncodePathSegment(eventId)),
@@ -285,6 +306,9 @@ var CalendarCreate = common.Shortcut{
 			"start":    startStr,
 			"end":      endStr,
 		}
+		if recurrence, _ := event["recurrence"].(string); recurrence != "" {
+			resultData["rrule"] = recurrence
+		}
 
 		runtime.OutFormat(resultData, nil, func(w io.Writer) {
 			var rows []map[string]interface{}

shortcuts/calendar/calendar_get.go

@@ -0,0 +1,279 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+//
+// calendar +get — get a single calendar event detail by calendar_id and event_id
+
+package calendar
+
+import (
+	"context"
+	"encoding/json"
+	"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"
+)
+
+// calendarEventTime mirrors start_time / end_time in the API response.
+type calendarEventTime struct {
+	Date      string `json:"date,omitempty"`
+	Timestamp string `json:"timestamp,omitempty"`
+	Timezone  string `json:"timezone,omitempty"`
+}
+
+// calendarEventVChat mirrors the vchat block in the API response.
+type calendarEventVChat struct {
+	VCType      string `json:"vc_type,omitempty"`
+	IconType    string `json:"icon_type,omitempty"`
+	Description string `json:"description,omitempty"`
+	MeetingURL  string `json:"meeting_url,omitempty"`
+}
+
+// calendarEventLocation mirrors the location block in the API response.
+type calendarEventLocation struct {
+	Name      string  `json:"name,omitempty"`
+	Address   string  `json:"address,omitempty"`
+	Latitude  float64 `json:"latitude,omitempty"`
+	Longitude float64 `json:"longitude,omitempty"`
+}
+
+// calendarEventReminder mirrors a reminder entry.
+type calendarEventReminder struct {
+	Minutes int `json:"minutes"`
+}
+
+// calendarEventOrganizer mirrors event_organizer.
+type calendarEventOrganizer struct {
+	UserID      string `json:"user_id,omitempty"`
+	DisplayName string `json:"display_name,omitempty"`
+}
+
+// calendarEventAttachment mirrors a single attachment entry.
+type calendarEventAttachment struct {
+	FileToken string `json:"file_token,omitempty"`
+	FileSize  string `json:"file_size,omitempty"`
+	Name      string `json:"name,omitempty"`
+}
+
+// calendarEventCheckInTime mirrors check_in_start_time / check_in_end_time.
+type calendarEventCheckInTime struct {
+	TimeType string `json:"time_type,omitempty"`
+	Duration int    `json:"duration"`
+}
+
+// calendarEventCheckIn mirrors event_check_in.
+type calendarEventCheckIn struct {
+	EnableCheckIn       bool                      `json:"enable_check_in"`
+	CheckInStartTime    *calendarEventCheckInTime `json:"check_in_start_time,omitempty"`
+	CheckInEndTime      *calendarEventCheckInTime `json:"check_in_end_time,omitempty"`
+	NeedNotifyAttendees bool                      `json:"need_notify_attendees"`
+}
+
+// calendarEvent mirrors the event object inside the API response.
+type calendarEvent struct {
+	EventID             string                    `json:"event_id,omitempty"`
+	OrganizerCalendarID string                    `json:"organizer_calendar_id,omitempty"`
+	Summary             string                    `json:"summary,omitempty"`
+	Description         string                    `json:"description,omitempty"`
+	StartTime           *calendarEventTime        `json:"start_time,omitempty"`
+	EndTime             *calendarEventTime        `json:"end_time,omitempty"`
+	VChat               *calendarEventVChat       `json:"vchat,omitempty"`
+	Visibility          string                    `json:"visibility,omitempty"`
+	AttendeeAbility     string                    `json:"attendee_ability,omitempty"`
+	FreeBusyStatus      string                    `json:"free_busy_status,omitempty"`
+	SelfRsvpStatus      string                    `json:"self_rsvp_status,omitempty"`
+	Location            *calendarEventLocation    `json:"location,omitempty"`
+	Color               int                       `json:"color,omitempty"`
+	Reminders           []calendarEventReminder   `json:"reminders,omitempty"`
+	Recurrence          string                    `json:"recurrence,omitempty"`
+	Status              string                    `json:"status,omitempty"`
+	IsException         bool                      `json:"is_exception,omitempty"`
+	RecurringEventID    string                    `json:"recurring_event_id,omitempty"`
+	CreateTime          string                    `json:"create_time,omitempty"`
+	EventOrganizer      *calendarEventOrganizer   `json:"event_organizer,omitempty"`
+	AppLink             string                    `json:"app_link,omitempty"`
+	Attachments         []calendarEventAttachment `json:"attachments,omitempty"`
+	EventCheckIn        *calendarEventCheckIn     `json:"event_check_in,omitempty"`
+}
+
+// parseCalendarEvent decodes the API response data into a typed calendarEvent.
+func parseCalendarEvent(data map[string]any) (*calendarEvent, error) {
+	rawEvent, ok := data["event"]
+	if !ok || rawEvent == nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event response missing 'event' field")
+	}
+	raw, err := json.Marshal(rawEvent)
+	if err != nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event response: marshal failed: %s", err).WithCause(err)
+	}
+	var event calendarEvent
+	if err := json.Unmarshal(raw, &event); err != nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event response: unmarshal failed: %s", err).WithCause(err)
+	}
+	return &event, nil
+}
+
+// buildCalendarEventOutput converts the typed event into the output map and
+// applies the four transformation rules:
+//  1. create_time -> RFC3339
+//  2. start_time / end_time timestamp -> datetime (RFC3339), drop timestamp
+//  3. flatten event into the top-level result
+//  4. when status != "cancelled", drop status (and adjust all-day end date)
+func buildCalendarEventOutput(event *calendarEvent) (map[string]interface{}, error) {
+	raw, err := json.Marshal(event)
+	if err != nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event marshal failed: %s", err).WithCause(err)
+	}
+	var out map[string]interface{}
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event unmarshal failed: %s", err).WithCause(err)
+	}
+
+	if ctStr, ok := out["create_time"].(string); ok && ctStr != "" {
+		if ts, err := strconv.ParseInt(ctStr, 10, 64); err == nil {
+			out["create_time"] = time.Unix(ts, 0).Local().Format(time.RFC3339)
+		}
+	}
+
+	if startMap, ok := out["start_time"].(map[string]interface{}); ok {
+		if tsStr, ok := startMap["timestamp"].(string); ok && tsStr != "" {
+			if ts, err := strconv.ParseInt(tsStr, 10, 64); err == nil {
+				startMap["datetime"] = time.Unix(ts, 0).Local().Format(time.RFC3339)
+				delete(startMap, "timestamp")
+			}
+		}
+	}
+	if endMap, ok := out["end_time"].(map[string]interface{}); ok {
+		if tsStr, ok := endMap["timestamp"].(string); ok && tsStr != "" {
+			if ts, err := strconv.ParseInt(tsStr, 10, 64); err == nil {
+				endMap["datetime"] = time.Unix(ts, 0).Local().Format(time.RFC3339)
+				delete(endMap, "timestamp")
+			}
+		}
+		// All-day event: end date is exclusive in the API; rewind by 1s and reformat.
+		if dt, _ := endMap["datetime"].(string); dt == "" {
+			if dateStr, ok := endMap["date"].(string); ok && dateStr != "" {
+				if t, err := time.ParseInLocation("2006-01-02", dateStr, time.UTC); err == nil {
+					endMap["date"] = t.Add(-1 * time.Second).Format("2006-01-02")
+				}
+			}
+		}
+	}
+
+	if status, _ := out["status"].(string); status != "cancelled" {
+		delete(out, "status")
+	}
+
+	return out, nil
+}
+
+// CalendarGet gets a single calendar event detail.
+var CalendarGet = common.Shortcut{
+	Service:     "calendar",
+	Command:     "+get",
+	Description: "Get a single calendar event detail by calendar-id and event-id",
+	Risk:        "read",
+	Scopes:      []string{"calendar:calendar.event:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "calendar-id", Desc: "calendar ID (default: primary)"},
+		{Name: "event-id", Desc: "event ID", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if err := rejectCalendarAutoBotFallback(runtime); err != nil {
+			return err
+		}
+		for _, flag := range []string{"calendar-id", "event-id"} {
+			if val := strings.TrimSpace(runtime.Str(flag)); val != "" {
+				if err := common.RejectDangerousCharsTyped("--"+flag, val); err != nil {
+					return err
+				}
+			}
+		}
+		eventId := strings.TrimSpace(runtime.Str("event-id"))
+		if eventId == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "event-id cannot be empty").WithParam("--event-id")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		calendarId := strings.TrimSpace(runtime.Str("calendar-id"))
+		d := common.NewDryRunAPI()
+		switch calendarId {
+		case "":
+			d.Desc("(calendar-id omitted) Will use primary calendar")
+			calendarId = "<primary>"
+		case "primary":
+			calendarId = "<primary>"
+		}
+		eventId := strings.TrimSpace(runtime.Str("event-id"))
+		return d.
+			GET("/open-apis/calendar/v4/calendars/:calendar_id/events/:event_id").
+			Set("calendar_id", calendarId).
+			Set("event_id", eventId)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		calendarId := strings.TrimSpace(runtime.Str("calendar-id"))
+		if calendarId == "" {
+			calendarId = PrimaryCalendarIDStr
+		}
+		eventId := strings.TrimSpace(runtime.Str("event-id"))
+
+		data, err := runtime.CallAPITyped("GET",
+			fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/%s",
+				validate.EncodePathSegment(calendarId),
+				validate.EncodePathSegment(eventId)),
+			nil, nil)
+		if err != nil {
+			return err
+		}
+
+		event, err := parseCalendarEvent(data)
+		if err != nil {
+			return err
+		}
+
+		out, err := buildCalendarEventOutput(event)
+		if err != nil {
+			return err
+		}
+
+		runtime.OutFormat(out, nil, func(w io.Writer) {
+			summary, _ := out["summary"].(string)
+			if summary == "" {
+				summary = "(untitled)"
+			}
+			startMap, _ := out["start_time"].(map[string]interface{})
+			endMap, _ := out["end_time"].(map[string]interface{})
+			startStr, _ := startMap["datetime"].(string)
+			if startStr == "" {
+				startStr, _ = startMap["date"].(string)
+			}
+			endStr, _ := endMap["datetime"].(string)
+			if endStr == "" {
+				endStr, _ = endMap["date"].(string)
+			}
+			eventIdOut, _ := out["event_id"].(string)
+			freeBusyStatus, _ := out["free_busy_status"].(string)
+			selfRsvpStatus, _ := out["self_rsvp_status"].(string)
+			row := map[string]interface{}{
+				"event_id":         eventIdOut,
+				"summary":          summary,
+				"start":            startStr,
+				"end":              endStr,
+				"free_busy_status": freeBusyStatus,
+				"self_rsvp_status": selfRsvpStatus,
+			}
+			output.PrintTable(w, []map[string]interface{}{row})
+			fmt.Fprintln(w)
+		})
+		return nil
+	},
+}

shortcuts/calendar/calendar_test.go

@@ -673,6 +673,76 @@ func TestCreate_WithAttendees_InvalidParamsWithDetail_RollsBack(t *testing.T) {
 	}
 }
 
+func TestCreate_ApprovalRoomMissingReason_GuidesRawAttendeesAPI(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"event": map[string]interface{}{
+					"event_id":   "evt_approval_room",
+					"summary":    "Approval Room",
+					"start_time": map[string]interface{}{"timestamp": "1742515200"},
+					"end_time":   map[string]interface{}{"timestamp": "1742518800"},
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/events/evt_approval_room/attendees",
+		Body: map[string]interface{}{
+			"code": codeInvalidParamsWithDetail,
+			"msg":  "invalid params",
+			"error": map[string]interface{}{
+				"details": []interface{}{
+					map[string]interface{}{"value": "attendees[0].approval_reason is required for approval meeting rooms"},
+				},
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/events/evt_approval_room",
+		Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+	})
+
+	err := mountAndRun(t, CalendarCreate, []string{
+		"+create",
+		"--summary", "Approval Room",
+		"--start", "2025-03-21T00:00:00+08:00",
+		"--end", "2025-03-21T01:00:00+08:00",
+		"--calendar-id", "cal_test123",
+		"--attendee-ids", "omm_room1",
+		"--as", "user",
+	}, f, nil)
+
+	if err == nil {
+		t.Fatal("expected error for approval room missing approval_reason, got nil")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("ProblemOf returned !ok for %T", err)
+	}
+	if p.Category != errs.CategoryAPI {
+		t.Errorf("category=%q, want %q", p.Category, errs.CategoryAPI)
+	}
+	if p.Subtype != errs.SubtypeInvalidParameters {
+		t.Errorf("subtype=%q, want %q", p.Subtype, errs.SubtypeInvalidParameters)
+	}
+	if p.Code != codeInvalidParamsWithDetail {
+		t.Errorf("code=%d, want %d", p.Code, codeInvalidParamsWithDetail)
+	}
+	for _, want := range []string{"approval_reason", "calendar event.attendees create", "--as user", "rolled back successfully"} {
+		if !strings.Contains(p.Hint, want) {
+			t.Errorf("hint should contain %q, got: %q", want, p.Hint)
+		}
+	}
+}
+
 // When the add-attendees call fails AND the rollback DELETE also fails, the
 // primary error stays the add failure (classification preserved) and the Hint
 // must surface BOTH the rollback failure reason and the orphan event_id so the
@@ -2234,17 +2304,17 @@ func TestResolveStartEnd_ExplicitValues(t *testing.T) {
 // Shortcuts() registration test
 // ---------------------------------------------------------------------------
 
-func TestShortcuts_Returns9(t *testing.T) {
+func TestShortcuts_Returns10(t *testing.T) {
 	shortcuts := Shortcuts()
-	if len(shortcuts) != 9 {
-		t.Fatalf("expected 9 shortcuts, got %d", len(shortcuts))
+	if len(shortcuts) != 10 {
+		t.Fatalf("expected 10 shortcuts, got %d", len(shortcuts))
 	}
 
 	names := map[string]bool{}
 	for _, s := range shortcuts {
 		names[s.Command] = true
 	}
-	for _, want := range []string{"+agenda", "+create", "+update", "+freebusy", "+room-find", "+rsvp", "+suggestion"} {
+	for _, want := range []string{"+agenda", "+create", "+update", "+freebusy", "+room-find", "+rsvp", "+suggestion", "+get"} {
 		if !names[want] {
 			t.Errorf("missing shortcut %s", want)
 		}
@@ -3108,3 +3178,193 @@ func TestSuggestion_RejectsDangerousTimezone_Typed(t *testing.T) {
 		t.Errorf("param=%q, want --timezone", ve.Param)
 	}
 }
+
+// ---------------------------------------------------------------------------
+// CalendarGet tests
+// ---------------------------------------------------------------------------
+
+func TestGet_Success_FlattensAndConvertsTimes(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events/evt_001",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{
+				"event": map[string]interface{}{
+					"event_id":    "evt_001",
+					"summary":     "Daily Sync",
+					"create_time": "1602504000",
+					"start_time": map[string]interface{}{
+						"timestamp": "1742515200",
+						"timezone":  "Asia/Shanghai",
+					},
+					"end_time": map[string]interface{}{
+						"timestamp": "1742518800",
+						"timezone":  "Asia/Shanghai",
+					},
+					"status": "confirmed",
+				},
+			},
+		},
+	})
+
+	err := mountAndRun(t, CalendarGet, []string{
+		"+get",
+		"--calendar-id", "cal_test123",
+		"--event-id", "evt_001",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	// Expect flattened — fields appear directly under "data", not under "data.event"
+	if strings.Contains(out, "\"event\": {") {
+		t.Errorf("payload should be flattened (no event wrapper), got: %s", out)
+	}
+	if !strings.Contains(out, "\"event_id\": \"evt_001\"") {
+		t.Errorf("expected event_id in output, got: %s", out)
+	}
+	// status=confirmed should be dropped
+	if strings.Contains(out, "\"status\": \"confirmed\"") {
+		t.Errorf("status should be dropped when not cancelled, got: %s", out)
+	}
+	// timestamp must be replaced with datetime
+	if strings.Contains(out, "\"timestamp\":") {
+		t.Errorf("timestamp should be replaced with datetime, got: %s", out)
+	}
+	if !strings.Contains(out, "\"datetime\":") {
+		t.Errorf("expected datetime in output, got: %s", out)
+	}
+	// create_time must be RFC3339 (contain 'T' and timezone)
+	if !strings.Contains(out, "\"create_time\": \"2020-10-12T") {
+		t.Errorf("expected RFC3339 create_time, got: %s", out)
+	}
+}
+
+func TestGet_CancelledStatus_PreservesStatus(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events/evt_002",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{
+				"event": map[string]interface{}{
+					"event_id":    "evt_002",
+					"summary":     "Cancelled Meeting",
+					"create_time": "1602504000",
+					"start_time":  map[string]interface{}{"timestamp": "1742515200"},
+					"end_time":    map[string]interface{}{"timestamp": "1742518800"},
+					"status":      "cancelled",
+				},
+			},
+		},
+	})
+
+	err := mountAndRun(t, CalendarGet, []string{
+		"+get",
+		"--calendar-id", "cal_test123",
+		"--event-id", "evt_002",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	if !strings.Contains(out, "\"status\": \"cancelled\"") {
+		t.Errorf("status should be preserved when cancelled, got: %s", out)
+	}
+}
+
+func TestGet_AllDayEvent_AdjustsEndDate(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	// All-day event: start 2025-03-21, end 2025-03-22 (exclusive in API).
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events/evt_003",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{
+				"event": map[string]interface{}{
+					"event_id":   "evt_003",
+					"summary":    "All-day",
+					"start_time": map[string]interface{}{"date": "2025-03-21"},
+					"end_time":   map[string]interface{}{"date": "2025-03-22"},
+					"status":     "confirmed",
+				},
+			},
+		},
+	})
+
+	err := mountAndRun(t, CalendarGet, []string{
+		"+get",
+		"--calendar-id", "cal_test123",
+		"--event-id", "evt_003",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	out := stdout.String()
+	// end date 2025-03-22 should rewind by 1s -> 2025-03-21
+	if !strings.Contains(out, "\"date\": \"2025-03-21\"") {
+		t.Errorf("expected end date adjusted to 2025-03-21, got: %s", out)
+	}
+}
+
+func TestGet_EmptyEventID_Typed(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, CalendarGet, []string{
+		"+get",
+		"--event-id", "   ",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("want error for empty event-id")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("want *errs.ValidationError, got %T", err)
+	}
+	if ve.Param != "--event-id" {
+		t.Errorf("param=%q, want --event-id", ve.Param)
+	}
+}
+
+func TestGet_MissingEventField_TypedInternal(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events/evt_404",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "success",
+			"data": map[string]interface{}{},
+		},
+	})
+
+	err := mountAndRun(t, CalendarGet, []string{
+		"+get",
+		"--calendar-id", "cal_test123",
+		"--event-id", "evt_404",
+		"--as", "bot",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("want error when event field is missing")
+	}
+	var ie *errs.InternalError
+	if !errors.As(err, &ie) {
+		t.Fatalf("want *errs.InternalError, got %T", err)
+	}
+	if ie.Subtype != errs.SubtypeInvalidResponse {
+		t.Errorf("subtype=%q, want invalid_response", ie.Subtype)
+	}
+}

shortcuts/calendar/shortcuts.go

@@ -17,5 +17,6 @@ func Shortcuts() []common.Shortcut {
 		CalendarSuggestion,
 		CalendarMeeting,
 		CalendarSearchEvent,
+		CalendarGet,
 	}
 }

shortcuts/doc/docs_history.go

@@ -0,0 +1,261 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type docsHistoryListSpec struct {
+	Doc       documentRef
+	PageSize  int
+	PageToken string
+}
+
+type docsHistoryRevertSpec struct {
+	Doc              documentRef
+	HistoryVersionID string
+	WaitTimeoutMs    int
+}
+
+type docsHistoryRevertStatusSpec struct {
+	Doc    documentRef
+	TaskID string
+}
+
+func parseDocsHistoryDocRef(raw, shortcut string) (documentRef, error) {
+	ref, err := parseDocumentRef(raw)
+	if err != nil {
+		return documentRef{}, err
+	}
+	if ref.Kind == "doc" {
+		return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "docs %s only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx", shortcut).WithParam("--doc")
+	}
+	return ref, nil
+}
+
+func validateDocsHistoryPageSize(pageSize int) error {
+	if pageSize < 1 || pageSize > 20 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --page-size %d: must be between 1 and 20", pageSize).WithParam("--page-size")
+	}
+	return nil
+}
+
+func validateDocsHistoryVersionID(historyVersionID string) error {
+	version, err := strconv.ParseInt(strings.TrimSpace(historyVersionID), 10, 64)
+	if err != nil {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--history-version-id must be a positive integer string returned by docs +history-list").WithParam("--history-version-id").WithCause(err)
+	}
+	if version <= 0 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--history-version-id must be a positive integer string returned by docs +history-list").WithParam("--history-version-id")
+	}
+	return nil
+}
+
+func validateDocsHistoryWaitTimeout(timeoutMs int) error {
+	if timeoutMs < 0 || timeoutMs > 30000 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --wait-timeout-ms %d: must be between 0 and 30000", timeoutMs).WithParam("--wait-timeout-ms")
+	}
+	return nil
+}
+
+func docsHistoryListParams(spec docsHistoryListSpec) map[string]interface{} {
+	params := map[string]interface{}{
+		"page_size": spec.PageSize,
+	}
+	if spec.PageToken != "" {
+		params["page_token"] = spec.PageToken
+	}
+	return params
+}
+
+func docsHistoryRevertBody(spec docsHistoryRevertSpec) map[string]interface{} {
+	return map[string]interface{}{
+		"history_version_id": spec.HistoryVersionID,
+		"wait_timeout_ms":    spec.WaitTimeoutMs,
+	}
+}
+
+func docsHistoryStatusParams(spec docsHistoryRevertStatusSpec) map[string]interface{} {
+	return map[string]interface{}{
+		"task_id": spec.TaskID,
+	}
+}
+
+func docsHistoryAPIPath(docToken, suffix string) string {
+	return fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/%s", validate.EncodePathSegment(docToken), suffix)
+}
+
+var DocsHistoryList = common.Shortcut{
+	Service:     "docs",
+	Command:     "+history-list",
+	Description: "List Lark document history versions",
+	Risk:        "read",
+	Scopes:      []string{"docx:document:readonly"},
+	AuthTypes:   []string{"user", "bot"},
+	PostMount:   installDocsShortcutHelp("+history-list"),
+	Flags: []common.Flag{
+		{Name: "doc", Desc: "document URL or token", Required: true},
+		{Name: "page-size", Type: "int", Default: "20", Desc: "history entries to return, range 1-20"},
+		{Name: "page-token", Desc: "pagination token from the previous page's page_token"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-list"); err != nil {
+			return err
+		}
+		return validateDocsHistoryPageSize(runtime.Int("page-size"))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-list")
+		spec := docsHistoryListSpec{
+			Doc:       ref,
+			PageSize:  runtime.Int("page-size"),
+			PageToken: strings.TrimSpace(runtime.Str("page-token")),
+		}
+		return common.NewDryRunAPI().
+			Desc("OpenAPI: list document history versions").
+			GET("/open-apis/docs_ai/v1/documents/:document_id/histories").
+			Set("document_id", spec.Doc.Token).
+			Params(docsHistoryListParams(spec))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-list")
+		spec := docsHistoryListSpec{
+			Doc:       ref,
+			PageSize:  runtime.Int("page-size"),
+			PageToken: strings.TrimSpace(runtime.Str("page-token")),
+		}
+
+		data, err := runtime.CallAPITyped(
+			http.MethodGet,
+			docsHistoryAPIPath(spec.Doc.Token, "histories"),
+			docsHistoryListParams(spec),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutRaw(data, nil)
+		return nil
+	},
+}
+
+var DocsHistoryRevert = common.Shortcut{
+	Service:     "docs",
+	Command:     "+history-revert",
+	Description: "Revert a Lark document to a historical version",
+	Risk:        "write",
+	Scopes:      []string{"docx:document:write_only", "docx:document:readonly"},
+	AuthTypes:   []string{"user", "bot"},
+	PostMount:   installDocsShortcutHelp("+history-revert"),
+	Flags: []common.Flag{
+		{Name: "doc", Desc: "document URL or token", Required: true},
+		{Name: "history-version-id", Desc: "history_version_id from docs +history-list to revert to", Required: true},
+		{Name: "wait-timeout-ms", Type: "int", Default: "30000", Desc: "milliseconds to wait for revert completion before returning, range 0-30000"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert"); err != nil {
+			return err
+		}
+		if err := validateDocsHistoryVersionID(runtime.Str("history-version-id")); err != nil {
+			return err
+		}
+		return validateDocsHistoryWaitTimeout(runtime.Int("wait-timeout-ms"))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert")
+		spec := docsHistoryRevertSpec{
+			Doc:              ref,
+			HistoryVersionID: strings.TrimSpace(runtime.Str("history-version-id")),
+			WaitTimeoutMs:    runtime.Int("wait-timeout-ms"),
+		}
+		return common.NewDryRunAPI().
+			Desc("OpenAPI: revert document history").
+			POST("/open-apis/docs_ai/v1/documents/:document_id/history/revert").
+			Set("document_id", spec.Doc.Token).
+			Body(docsHistoryRevertBody(spec))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert")
+		spec := docsHistoryRevertSpec{
+			Doc:              ref,
+			HistoryVersionID: strings.TrimSpace(runtime.Str("history-version-id")),
+			WaitTimeoutMs:    runtime.Int("wait-timeout-ms"),
+		}
+
+		data, err := runtime.CallAPITyped(
+			http.MethodPost,
+			docsHistoryAPIPath(spec.Doc.Token, "history/revert"),
+			nil,
+			docsHistoryRevertBody(spec),
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutRaw(data, nil)
+		return nil
+	},
+}
+
+var DocsHistoryRevertStatus = common.Shortcut{
+	Service:     "docs",
+	Command:     "+history-revert-status",
+	Description: "Get Lark document history revert task status",
+	Risk:        "read",
+	Scopes:      []string{"docx:document:readonly"},
+	AuthTypes:   []string{"user", "bot"},
+	PostMount:   installDocsShortcutHelp("+history-revert-status"),
+	Flags: []common.Flag{
+		{Name: "doc", Desc: "document URL or token", Required: true},
+		{Name: "task-id", Desc: "task_id returned by docs +history-revert", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert-status"); err != nil {
+			return err
+		}
+		if strings.TrimSpace(runtime.Str("task-id")) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--task-id is required").WithParam("--task-id")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert-status")
+		spec := docsHistoryRevertStatusSpec{
+			Doc:    ref,
+			TaskID: strings.TrimSpace(runtime.Str("task-id")),
+		}
+		return common.NewDryRunAPI().
+			Desc("OpenAPI: get document history revert status").
+			GET("/open-apis/docs_ai/v1/documents/:document_id/history/revert_status").
+			Set("document_id", spec.Doc.Token).
+			Params(docsHistoryStatusParams(spec))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert-status")
+		spec := docsHistoryRevertStatusSpec{
+			Doc:    ref,
+			TaskID: strings.TrimSpace(runtime.Str("task-id")),
+		}
+
+		data, err := runtime.CallAPITyped(
+			http.MethodGet,
+			docsHistoryAPIPath(spec.Doc.Token, "history/revert_status"),
+			docsHistoryStatusParams(spec),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutRaw(data, nil)
+		return nil
+	},
+}

shortcuts/doc/docs_history_test.go

@@ -0,0 +1,340 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"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"
+	"github.com/spf13/cobra"
+)
+
+func TestDocsHistoryValidation(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		shortcut  common.Shortcut
+		args      []string
+		param     string
+		category  errs.Category
+		subtype   errs.Subtype
+		wantCause bool
+	}{
+		{
+			name:     "list rejects legacy doc URL",
+			shortcut: DocsHistoryList,
+			args:     []string{"+history-list", "--doc", "https://example.feishu.cn/doc/old_doc", "--as", "bot"},
+			param:    "--doc",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+		{
+			name:     "list rejects invalid page size",
+			shortcut: DocsHistoryList,
+			args:     []string{"+history-list", "--doc", "doxcnHistory", "--page-size", "0", "--as", "bot"},
+			param:    "--page-size",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+		{
+			name:      "revert rejects non-numeric history version id",
+			shortcut:  DocsHistoryRevert,
+			args:      []string{"+history-revert", "--doc", "doxcnHistory", "--history-version-id", "abc", "--as", "bot"},
+			param:     "--history-version-id",
+			category:  errs.CategoryValidation,
+			subtype:   errs.SubtypeInvalidArgument,
+			wantCause: true,
+		},
+		{
+			name:     "revert rejects non-positive history version id",
+			shortcut: DocsHistoryRevert,
+			args:     []string{"+history-revert", "--doc", "doxcnHistory", "--history-version-id", "0", "--as", "bot"},
+			param:    "--history-version-id",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+		{
+			name:     "revert rejects invalid wait timeout",
+			shortcut: DocsHistoryRevert,
+			args:     []string{"+history-revert", "--doc", "doxcnHistory", "--history-version-id", "10", "--wait-timeout-ms", "30001", "--as", "bot"},
+			param:    "--wait-timeout-ms",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+		{
+			name:     "status rejects empty task id",
+			shortcut: DocsHistoryRevertStatus,
+			args:     []string{"+history-revert-status", "--doc", "doxcnHistory", "--task-id", "", "--as", "bot"},
+			param:    "--task-id",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-validation"))
+			err := mountAndRunDocs(t, tt.shortcut, tt.args, f, stdout)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("error is not typed: %T %v", err, err)
+			}
+			if problem.Category != tt.category {
+				t.Fatalf("category = %q, want %q (err: %v)", problem.Category, tt.category, err)
+			}
+			if problem.Subtype != tt.subtype {
+				t.Fatalf("subtype = %q, want %q (err: %v)", problem.Subtype, tt.subtype, err)
+			}
+			var validationErr *errs.ValidationError
+			if !errors.As(err, &validationErr) {
+				t.Fatalf("expected validation error, got %T: %v", err, err)
+			}
+			if validationErr.Param != tt.param {
+				t.Fatalf("param = %q, want %q (err: %v)", validationErr.Param, tt.param, err)
+			}
+			if tt.wantCause && errors.Unwrap(err) == nil {
+				t.Fatalf("expected wrapped cause, got nil (err: %v)", err)
+			}
+		})
+	}
+}
+
+func TestDocsHistoryDryRun(t *testing.T) {
+	t.Parallel()
+
+	listCmd := newDocsHistoryRuntimeCmd(t, DocsHistoryList, map[string]string{
+		"doc":        "doxcnHistoryDryRun",
+		"page-size":  "5",
+		"page-token": "page_token_1",
+	})
+	listDry := decodeDocDryRun(t, DocsHistoryList.DryRun(context.Background(), common.TestNewRuntimeContext(listCmd, nil)))
+	if got, want := listDry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnHistoryDryRun/histories"; got != want {
+		t.Fatalf("list dry-run URL = %q, want %q", got, want)
+	}
+	if got := int(listDry.API[0].Params["page_size"].(float64)); got != 5 {
+		t.Fatalf("list page_size = %d, want 5", got)
+	}
+	if got := listDry.API[0].Params["page_token"]; got != "page_token_1" {
+		t.Fatalf("list page_token = %#v, want page_token_1", got)
+	}
+
+	revertCmd := newDocsHistoryRuntimeCmd(t, DocsHistoryRevert, map[string]string{
+		"doc":                "doxcnHistoryDryRun",
+		"history-version-id": "42",
+		"wait-timeout-ms":    "30000",
+	})
+	revertDry := decodeDocDryRun(t, DocsHistoryRevert.DryRun(context.Background(), common.TestNewRuntimeContext(revertCmd, nil)))
+	if got, want := revertDry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnHistoryDryRun/history/revert"; got != want {
+		t.Fatalf("revert dry-run URL = %q, want %q", got, want)
+	}
+	if got := revertDry.API[0].Body["history_version_id"]; got != "42" {
+		t.Fatalf("revert history_version_id = %#v, want 42", got)
+	}
+	if got := int(revertDry.API[0].Body["wait_timeout_ms"].(float64)); got != 30000 {
+		t.Fatalf("revert wait_timeout_ms = %d, want 30000", got)
+	}
+
+	statusCmd := newDocsHistoryRuntimeCmd(t, DocsHistoryRevertStatus, map[string]string{
+		"doc":     "doxcnHistoryDryRun",
+		"task-id": "task_1",
+	})
+	statusDry := decodeDocDryRun(t, DocsHistoryRevertStatus.DryRun(context.Background(), common.TestNewRuntimeContext(statusCmd, nil)))
+	if got, want := statusDry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnHistoryDryRun/history/revert_status"; got != want {
+		t.Fatalf("status dry-run URL = %q, want %q", got, want)
+	}
+	if got := statusDry.API[0].Params["task_id"]; got != "task_1" {
+		t.Fatalf("status task_id = %#v, want task_1", got)
+	}
+}
+
+func TestDocsHistoryExecuteList(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-list"))
+	stub := &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/docs_ai/v1/documents/doxcnHistory/histories",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"entries": []interface{}{
+					map[string]interface{}{
+						"revision_id":        float64(42),
+						"history_version_id": "11",
+						"edit_time":          "1780000000",
+						"type":               float64(1),
+						"editor_ids":         []interface{}{"ou_1"},
+					},
+				},
+				"has_more":   true,
+				"page_token": "page_token_2",
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRunDocs(t, DocsHistoryList, []string{
+		"+history-list",
+		"--doc", "doxcnHistory",
+		"--page-size", "5",
+		"--page-token", "page_token_1",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDocsHistoryEnvelope(t, stdout)
+	if got := data["page_token"]; got != "page_token_2" {
+		t.Fatalf("page_token = %#v, want page_token_2", got)
+	}
+	entries, _ := data["entries"].([]interface{})
+	if len(entries) != 1 {
+		t.Fatalf("entries = %#v, want one entry", data["entries"])
+	}
+}
+
+func TestDocsHistoryExecuteRevert(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-revert"))
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/docs_ai/v1/documents/doxcnHistory/history/revert",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"task_id":            "task_1",
+				"status":             "running",
+				"history_version_id": "42",
+				"poll_after_ms":      float64(10000),
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRunDocs(t, DocsHistoryRevert, []string{
+		"+history-revert",
+		"--doc", "doxcnHistory",
+		"--history-version-id", "42",
+		"--wait-timeout-ms", "0",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("decode revert body: %v\nraw=%s", err, stub.CapturedBody)
+	}
+	if got := body["history_version_id"]; got != "42" {
+		t.Fatalf("history_version_id = %#v, want 42", got)
+	}
+	if got := int(body["wait_timeout_ms"].(float64)); got != 0 {
+		t.Fatalf("wait_timeout_ms = %d, want 0", got)
+	}
+
+	data := decodeDocsHistoryEnvelope(t, stdout)
+	if got := data["task_id"]; got != "task_1" {
+		t.Fatalf("task_id = %#v, want task_1", got)
+	}
+}
+
+func TestDocsHistoryExecuteRevertStatus(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-status"))
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/docs_ai/v1/documents/doxcnHistory/history/revert_status",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"status":              "partial_failed",
+				"history_version_id":  "11",
+				"failed_block_tokens": []interface{}{"blk_1"},
+			},
+		},
+	})
+
+	err := mountAndRunDocs(t, DocsHistoryRevertStatus, []string{
+		"+history-revert-status",
+		"--doc", "doxcnHistory",
+		"--task-id", "task_1",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDocsHistoryEnvelope(t, stdout)
+	if got := data["status"]; got != "partial_failed" {
+		t.Fatalf("status = %#v, want partial_failed", got)
+	}
+	if got := data["history_version_id"]; got != "11" {
+		t.Fatalf("history_version_id = %#v, want 11", got)
+	}
+	failed, _ := data["failed_block_tokens"].([]interface{})
+	if len(failed) != 1 || failed[0] != "blk_1" {
+		t.Fatalf("failed_block_tokens = %#v, want [blk_1]", data["failed_block_tokens"])
+	}
+}
+
+func newDocsHistoryRuntimeCmd(t *testing.T, shortcut common.Shortcut, values map[string]string) *cobra.Command {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: shortcut.Command}
+	for _, flag := range shortcut.Flags {
+		switch flag.Type {
+		case "int":
+			cmd.Flags().Int(flag.Name, 0, flag.Desc)
+		default:
+			cmd.Flags().String(flag.Name, flag.Default, flag.Desc)
+		}
+	}
+	for name, value := range values {
+		if err := cmd.Flags().Set(name, value); err != nil {
+			t.Fatalf("set --%s: %v", name, err)
+		}
+	}
+	return cmd
+}
+
+func decodeDocsHistoryEnvelope(t *testing.T, stdout *bytes.Buffer) map[string]interface{} {
+	t.Helper()
+
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("decode envelope: %v\nraw=%s", err, stdout.String())
+	}
+	data, _ := envelope["data"].(map[string]interface{})
+	if data == nil {
+		t.Fatalf("missing data in envelope: %#v", envelope)
+	}
+	return data
+}
+
+func TestDocsHistoryURLValidationMessage(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseDocsHistoryDocRef("https://example.feishu.cn/doc/old_doc", "+history-list")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "only supports docx documents") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}

shortcuts/doc/shortcuts.go

@@ -31,6 +31,8 @@ func docsSkillReadCommandForShortcut(shortcut string) string {
 		return docsSkillReadCommand + " references/lark-doc-fetch.md"
 	case "update":
 		return docsSkillReadCommand + " references/lark-doc-update.md"
+	case "history-list", "history-revert", "history-revert-status":
+		return docsSkillReadCommand + " references/lark-doc-history.md"
 	default:
 		return docsSkillReadCommand
 	}
@@ -44,6 +46,12 @@ func docsHelpCommandForShortcut(shortcut string) string {
 		return "lark-cli docs +fetch --help"
 	case "update":
 		return "lark-cli docs +update --help"
+	case "history-list":
+		return "lark-cli docs +history-list --help"
+	case "history-revert":
+		return "lark-cli docs +history-revert --help"
+	case "history-revert-status":
+		return "lark-cli docs +history-revert-status --help"
 	default:
 		return "lark-cli docs --help"
 	}
@@ -56,6 +64,9 @@ func Shortcuts() []common.Shortcut {
 		DocsCreate,
 		DocsFetch,
 		DocsUpdate,
+		DocsHistoryList,
+		DocsHistoryRevert,
+		DocsHistoryRevertStatus,
 		DocMediaInsert,
 		DocMediaUpload,
 		DocMediaPreview,

shortcuts/drive/drive_import_common.go

@@ -8,6 +8,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"time"
 
@@ -28,6 +29,8 @@ const (
 	driveImport500MBFileSizeLimit int64 = 500 * 1024 * 1024
 	driveImport600MBFileSizeLimit int64 = 600 * 1024 * 1024
 	driveImport800MBFileSizeLimit int64 = 800 * 1024 * 1024
+
+	driveImportConcurrentOperationHint = "This import conflict means another operation is running in the same Drive location. Run batch imports to the same folder/root or target bitable serially. Wait a few seconds before retrying each failed import; retry each failed item at most 3 times, then stop and report the conflict."
 )
 
 // driveImportExtToDocTypes defines which source file extensions can be imported
@@ -47,6 +50,8 @@ var driveImportExtToDocTypes = map[string][]string{
 	"pptx":     {"slides"},
 }
 
+var driveImportConcurrentOperationCodes = []int{232140101, 232140100, 233523001}
+
 // driveImportSpec contains the user-facing import inputs after normalization.
 type driveImportSpec struct {
 	FilePath    string
@@ -427,11 +432,7 @@ func pollDriveImportTask(runtime *common.RuntimeContext, ticket string) (driveIm
 			return status, true, nil
 		}
 		if status.Failed() {
-			msg := strings.TrimSpace(status.JobErrorMsg)
-			if msg == "" {
-				msg = status.StatusLabel()
-			}
-			return status, false, errs.NewAPIError(errs.SubtypeServerError, "import failed with status %d: %s", status.JobStatus, msg)
+			return status, false, driveImportFailureError(status)
 		}
 	}
 	if !hadSuccessfulPoll && lastErr != nil {
@@ -440,3 +441,40 @@ func pollDriveImportTask(runtime *common.RuntimeContext, ticket string) (driveIm
 
 	return lastStatus, false, nil
 }
+
+func driveImportFailureError(status driveImportStatus) *errs.APIError {
+	msg := strings.TrimSpace(status.JobErrorMsg)
+	if msg == "" {
+		msg = status.StatusLabel()
+	}
+
+	apiErr := errs.NewAPIError(errs.SubtypeServerError, "import failed with status %d: %s", status.JobStatus, msg)
+	if code, ok := driveImportConcurrentOperationCode(msg); ok {
+		apiErr = apiErr.WithCode(code).WithRetryable().WithHint(driveImportConcurrentOperationHint)
+	}
+	return apiErr
+}
+
+func driveImportConcurrentOperationCode(msg string) (int, bool) {
+	for _, code := range driveImportConcurrentOperationCodes {
+		codeText := strconv.Itoa(code)
+		for idx := strings.Index(msg, codeText); idx >= 0; {
+			end := idx + len(codeText)
+			if (idx == 0 || !isASCIIDigit(msg[idx-1])) && (end == len(msg) || !isASCIIDigit(msg[end])) {
+				return code, true
+			}
+
+			nextStart := idx + 1
+			next := strings.Index(msg[nextStart:], codeText)
+			if next < 0 {
+				break
+			}
+			idx = nextStart + next
+		}
+	}
+	return 0, false
+}
+
+func isASCIIDigit(ch byte) bool {
+	return ch >= '0' && ch <= '9'
+}

shortcuts/drive/drive_import_common_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"errors"
 	"os"
+	"strconv"
 	"strings"
 	"testing"
 
@@ -211,6 +212,82 @@ func TestDriveImportStatusPendingWithoutToken(t *testing.T) {
 	}
 }
 
+func TestDriveImportFailureErrorAddsConcurrentOperationGuidance(t *testing.T) {
+	t.Parallel()
+
+	for _, code := range driveImportConcurrentOperationCodes {
+		t.Run(strconv.Itoa(code), func(t *testing.T) {
+			t.Parallel()
+
+			err := driveImportFailureError(driveImportStatus{
+				JobStatus:   3,
+				JobErrorMsg: "call CreateObjNode return error code, code: " + strconv.Itoa(code) + ", message:",
+			})
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("expected typed error, got %T", err)
+			}
+			if problem.Category != errs.CategoryAPI {
+				t.Fatalf("category = %q, want %q", problem.Category, errs.CategoryAPI)
+			}
+			if problem.Subtype != errs.SubtypeServerError {
+				t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeServerError)
+			}
+			if problem.Code != code {
+				t.Fatalf("code = %d, want %d", problem.Code, code)
+			}
+			if !problem.Retryable {
+				t.Fatal("expected retryable error")
+			}
+			if problem.Hint != driveImportConcurrentOperationHint {
+				t.Fatalf("hint = %q, want %q", problem.Hint, driveImportConcurrentOperationHint)
+			}
+		})
+	}
+}
+
+func TestDriveImportFailureErrorLeavesOtherFailuresUnchanged(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name string
+		msg  string
+	}{
+		{
+			name: "ordinary failure",
+			msg:  "unsupported conversion",
+		},
+		{
+			name: "longer numeric code containing known code",
+			msg:  "call CreateObjNode return error code, code: 12321401012, message:",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := driveImportFailureError(driveImportStatus{
+				JobStatus:   3,
+				JobErrorMsg: tt.msg,
+			})
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("expected typed error, got %T", err)
+			}
+			if problem.Code != 0 {
+				t.Fatalf("code = %d, want 0", problem.Code)
+			}
+			if problem.Retryable {
+				t.Fatal("expected non-concurrency failure to remain non-retryable")
+			}
+			if problem.Hint != "" {
+				t.Fatalf("hint = %q, want empty", problem.Hint)
+			}
+		})
+	}
+}
+
 func TestDriveImportTimeoutReturnsFollowUpCommand(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 	reg.Register(&httpmock.Stub{

shortcuts/minutes/minutes_detail.go

@@ -28,7 +28,12 @@ import (
 const minutesDetailLogPrefix = "[minutes +detail]"
 
 // Error codes from the minutes API.
-const minutesDetailNoReadPermissionCode = 2091005
+const (
+	minutesDetailProcessingCode       = 2091003
+	minutesDetailNoReadPermissionCode = 2091005
+	minutesDetailWaitTimeoutDefault   = 300
+	minutesDetailWaitIntervalDefault  = 15
+)
 
 var validMinuteTokenDetail = regexp.MustCompile(`^[a-z0-9]+$`)
 
@@ -40,19 +45,31 @@ var scopesDetailMinuteTokens = []string{
 // minuteDetailItem represents a single minute detail result.
 type minuteDetailItem struct {
 	MinuteToken string         `json:"minute_token"`
+	Status      string         `json:"status,omitempty"`
 	Title       string         `json:"title"`
 	NoteID      string         `json:"note_id"`
 	Artifacts   map[string]any `json:"artifacts,omitempty"`
+	Retryable   bool           `json:"retryable,omitempty"`
 	Error       string         `json:"error,omitempty"`
+	Hint        string         `json:"hint,omitempty"`
+	NextCommand string         `json:"next_command,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)
+	artifactFlags := requestedMinutesDetailArtifactFlags(runtime)
+	waitReady := runtime.Bool("wait-ready")
+	waitTimeout, waitInterval := minutesDetailWaitConfig(runtime)
+
+	data, err := callMinutesDetailAPIUntilReady(ctx, runtime, waitReady, waitTimeout, waitInterval, func() (map[string]interface{}, error) {
+		return 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 {
+		if isMinutesDetailProcessingError(err) {
+			markMinutesDetailProcessing(result, minuteToken, artifactFlags, "minute metadata is still being generated")
+		} else 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)
@@ -81,10 +98,16 @@ func fetchMinuteDetail(ctx context.Context, runtime *common.RuntimeContext, minu
 	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)
+		artData, err := callMinutesDetailAPIUntilReady(ctx, runtime, waitReady, waitTimeout, waitInterval, func() (map[string]interface{}, error) {
+			return 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)
+			if isMinutesDetailProcessingError(err) {
+				markMinutesDetailProcessing(result, minuteToken, artifactFlags, "minute artifacts are still being generated")
+			} else {
+				result.Error = fmt.Sprintf("failed to query minute artifacts: %v", err)
+			}
 		} else {
 			artifacts := make(map[string]any)
 			if needSummary {
@@ -133,6 +156,78 @@ func fetchMinuteDetail(ctx context.Context, runtime *common.RuntimeContext, minu
 	return result
 }
 
+func isMinutesDetailProcessingError(err error) bool {
+	if p, ok := errs.ProblemOf(err); ok && p.Code == minutesDetailProcessingCode {
+		return true
+	}
+	return false
+}
+
+func minutesDetailWaitConfig(runtime *common.RuntimeContext) (time.Duration, time.Duration) {
+	timeoutSeconds, intervalSeconds := normalizeMinutesDetailWaitSeconds(runtime.Int("wait-timeout-seconds"), runtime.Int("wait-interval-seconds"))
+	return time.Duration(timeoutSeconds) * time.Second, time.Duration(intervalSeconds) * time.Second
+}
+
+func normalizeMinutesDetailWaitSeconds(timeoutSeconds, intervalSeconds int) (int, int) {
+	if timeoutSeconds <= 0 {
+		timeoutSeconds = minutesDetailWaitTimeoutDefault
+	}
+	if intervalSeconds <= 0 {
+		intervalSeconds = minutesDetailWaitIntervalDefault
+	}
+	return timeoutSeconds, intervalSeconds
+}
+
+func callMinutesDetailAPIUntilReady(ctx context.Context, runtime *common.RuntimeContext, waitReady bool, timeout, interval time.Duration, call func() (map[string]interface{}, error)) (map[string]interface{}, error) {
+	deadline := time.Now().Add(timeout)
+	for {
+		data, err := call()
+		if err == nil || !waitReady || !isMinutesDetailProcessingError(err) {
+			return data, err
+		}
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			return nil, ctxErr
+		}
+		remaining := time.Until(deadline)
+		if remaining <= 0 || interval > remaining {
+			return nil, err
+		}
+		fmt.Fprintf(runtime.IO().ErrOut, "%s minute is still processing; retrying in %s\n", minutesDetailLogPrefix, interval)
+		timer := time.NewTimer(interval)
+		select {
+		case <-ctx.Done():
+			timer.Stop()
+			return nil, ctx.Err()
+		case <-timer.C:
+		}
+	}
+}
+
+func requestedMinutesDetailArtifactFlags(runtime *common.RuntimeContext) []string {
+	var flags []string
+	for _, flag := range []string{"summary", "todo", "chapter", "keyword", "transcript"} {
+		if runtime.Bool(flag) {
+			flags = append(flags, "--"+flag)
+		}
+	}
+	return flags
+}
+
+func markMinutesDetailProcessing(result *minuteDetailItem, minuteToken string, artifactFlags []string, reason string) {
+	result.Status = "processing"
+	result.Retryable = true
+	result.Error = reason
+	result.Hint = "The minute is still being generated. Retry later, or rerun the next_command to wait until it is ready."
+	result.NextCommand = minutesDetailNextCommand(minuteToken, artifactFlags)
+}
+
+func minutesDetailNextCommand(minuteToken string, artifactFlags []string) string {
+	parts := []string{"lark-cli", "minutes", "+detail", "--minute-tokens", minuteToken}
+	parts = append(parts, artifactFlags...)
+	parts = append(parts, "--wait-ready")
+	return strings.Join(parts, " ")
+}
+
 // 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
@@ -201,6 +296,9 @@ var MinutesDetail = common.Shortcut{
 		{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"},
+		{Name: "wait-ready", Type: "bool", Desc: "wait until minute metadata/artifacts are ready", Hidden: true},
+		{Name: "wait-timeout-seconds", Type: "int", Default: "300", Desc: "maximum seconds to wait for readiness", Hidden: true},
+		{Name: "wait-interval-seconds", Type: "int", Default: "15", Desc: "seconds between readiness checks", Hidden: true},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		tokens := common.SplitCSV(runtime.Str("minute-tokens"))
@@ -282,8 +380,15 @@ var MinutesDetail = common.Shortcut{
 			for _, r := range results {
 				row := map[string]interface{}{"minute_token": r.MinuteToken}
 				if r.Error != "" {
-					row["status"] = "FAIL"
+					if r.Status == "processing" {
+						row["status"] = "PROCESSING"
+					} else {
+						row["status"] = "FAIL"
+					}
 					row["error"] = r.Error
+					if r.NextCommand != "" {
+						row["next_command"] = r.NextCommand
+					}
 				} else {
 					row["status"] = "OK"
 					row["title"] = r.Title

shortcuts/minutes/minutes_detail_test.go

@@ -9,6 +9,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"net/http"
 	"os"
 	"strings"
 	"sync"
@@ -108,6 +109,17 @@ func detailArtifactsStub(token, transcript string) *httpmock.Stub {
 	}
 }
 
+func detailProcessingStub(path string) *httpmock.Stub {
+	return &httpmock.Stub{
+		Method: "GET",
+		URL:    path,
+		Body: map[string]interface{}{
+			"code": 2091003,
+			"msg":  "minute is processing",
+		},
+	}
+}
+
 func TestDetail_Validation_MissingMinuteTokens(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
 	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--as", "user"}, f, nil)
@@ -172,6 +184,34 @@ func TestDetail_DryRun_WithArtifactFlags(t *testing.T) {
 	}
 }
 
+func TestDetail_HiddenWaitFlags(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	parent := &cobra.Command{Use: "minutes"}
+	MinutesDetail.Mount(parent, f)
+	parent.SetOut(stdout)
+	parent.SetArgs([]string{"+detail", "--help"})
+	parent.SilenceErrors = true
+	parent.SilenceUsage = true
+	if err := parent.Execute(); err != nil {
+		t.Fatalf("help failed: %v", err)
+	}
+	help := stdout.String()
+	for _, hidden := range []string{"wait-ready", "wait-timeout-seconds", "wait-interval-seconds"} {
+		if strings.Contains(help, hidden) {
+			t.Fatalf("hidden flag %q should not appear in help:\n%s", hidden, help)
+		}
+	}
+
+	stdout.Reset()
+	err := detailMountAndRun(t, MinutesDetail, []string{
+		"+detail", "--minute-tokens", "tok001", "--summary", "--wait-ready",
+		"--wait-timeout-seconds", "0", "--wait-interval-seconds", "0", "--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("hidden wait flags should parse: %v", err)
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Execute tests with mocked HTTP
 // ---------------------------------------------------------------------------
@@ -355,6 +395,136 @@ func TestDetail_Execute_MinuteNotFound(t *testing.T) {
 	}
 }
 
+func TestDetail_Execute_MetadataProcessing(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/tokpending"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokpending", "--summary", "--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)
+	}
+	m := firstDetailMinute(t, stdout.Bytes())
+	if m["status"] != "processing" {
+		t.Fatalf("status = %v, want processing", m["status"])
+	}
+	if m["retryable"] != true {
+		t.Fatalf("retryable = %v, want true", m["retryable"])
+	}
+	if !strings.Contains(fmt.Sprint(m["next_command"]), "minutes +detail --minute-tokens tokpending --summary --wait-ready") {
+		t.Fatalf("next_command = %v", m["next_command"])
+	}
+}
+
+func TestDetail_Execute_ArtifactsProcessing(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("tokartpending", "note_pending", "Pending Artifacts"))
+	reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/tokartpending/artifacts"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokartpending", "--summary", "--todo", "--as", "user"}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+	m := firstDetailMinute(t, stdout.Bytes())
+	if m["status"] != "processing" {
+		t.Fatalf("status = %v, want processing", m["status"])
+	}
+	if m["title"] != "Pending Artifacts" || m["note_id"] != "note_pending" {
+		t.Fatalf("metadata should be preserved on artifacts processing, got title=%v note_id=%v", m["title"], m["note_id"])
+	}
+	if !strings.Contains(fmt.Sprint(m["next_command"]), "--summary --todo --wait-ready") {
+		t.Fatalf("next_command = %v", m["next_command"])
+	}
+}
+
+func TestDetail_WaitReady_MetadataEventuallyReady(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/tokwaitmeta"))
+	reg.Register(detailMinuteGetStub("tokwaitmeta", "", "Ready Metadata"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{
+		"+detail", "--minute-tokens", "tokwaitmeta", "--wait-ready",
+		"--wait-timeout-seconds", "5", "--wait-interval-seconds", "1", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	m := firstDetailMinute(t, stdout.Bytes())
+	if m["title"] != "Ready Metadata" {
+		t.Fatalf("title = %v, want Ready Metadata", m["title"])
+	}
+	if _, ok := m["artifacts"]; ok {
+		t.Fatal("artifacts should not be fetched without artifact flags")
+	}
+}
+
+func TestDetail_WaitReady_ArtifactsEventuallyReady(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("tokwaitart", "note_wait", "Ready Artifacts"))
+	reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/tokwaitart/artifacts"))
+	reg.Register(detailArtifactsStub("tokwaitart", ""))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{
+		"+detail", "--minute-tokens", "tokwaitart", "--summary", "--wait-ready",
+		"--wait-timeout-seconds", "5", "--wait-interval-seconds", "1", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	m := firstDetailMinute(t, stdout.Bytes())
+	arts, _ := m["artifacts"].(map[string]any)
+	if arts == nil {
+		t.Fatal("expected artifacts")
+	}
+	if arts["summary"] != "Test summary content" {
+		t.Fatalf("summary = %v", arts["summary"])
+	}
+}
+
+func TestDetail_WaitReady_TimeoutUsesProcessingResult(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(detailMinuteGetStub("toktimeout", "note_timeout", "Timeout Artifacts"))
+	reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/toktimeout/artifacts"))
+
+	err := detailMountAndRun(t, MinutesDetail, []string{
+		"+detail", "--minute-tokens", "toktimeout", "--summary", "--wait-ready",
+		"--wait-timeout-seconds", "1", "--wait-interval-seconds", "2", "--as", "user",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+	m := firstDetailMinute(t, stdout.Bytes())
+	if m["status"] != "processing" || m["title"] != "Timeout Artifacts" || m["note_id"] != "note_timeout" {
+		t.Fatalf("timeout should preserve processing status and metadata, got %+v", m)
+	}
+}
+
+func TestDetail_WaitReady_DoesNotPollNonProcessingErrors(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	var callCount int
+	reg.Register(&httpmock.Stub{
+		Method:   "GET",
+		URL:      "/open-apis/minutes/v1/minutes/tokmissing",
+		Body:     map[string]interface{}{"code": 2091004, "msg": "not found"},
+		Reusable: true,
+		OnMatch:  func(req *http.Request) { callCount++ },
+	})
+
+	err := detailMountAndRun(t, MinutesDetail, []string{
+		"+detail", "--minute-tokens", "tokmissing", "--wait-ready",
+		"--wait-timeout-seconds", "5", "--wait-interval-seconds", "1", "--as", "user",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected partial failure error")
+	}
+	if callCount != 1 {
+		t.Fatalf("non-processing error should not be retried, callCount=%d", callCount)
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Pure function tests
 // ---------------------------------------------------------------------------
@@ -378,6 +548,36 @@ func TestValidMinuteTokenDetail(t *testing.T) {
 	}
 }
 
+func TestNormalizeMinutesDetailWaitSeconds(t *testing.T) {
+	timeout, interval := normalizeMinutesDetailWaitSeconds(0, 0)
+	if timeout != minutesDetailWaitTimeoutDefault || interval != minutesDetailWaitIntervalDefault {
+		t.Fatalf("normalize(0,0) = (%d,%d), want defaults (%d,%d)", timeout, interval, minutesDetailWaitTimeoutDefault, minutesDetailWaitIntervalDefault)
+	}
+	timeout, interval = normalizeMinutesDetailWaitSeconds(-1, -2)
+	if timeout != minutesDetailWaitTimeoutDefault || interval != minutesDetailWaitIntervalDefault {
+		t.Fatalf("normalize(negative) = (%d,%d), want defaults", timeout, interval)
+	}
+	timeout, interval = normalizeMinutesDetailWaitSeconds(9, 3)
+	if timeout != 9 || interval != 3 {
+		t.Fatalf("normalize(9,3) = (%d,%d)", timeout, interval)
+	}
+}
+
+func firstDetailMinute(t *testing.T, raw []byte) map[string]any {
+	t.Helper()
+	var resp map[string]any
+	if err := json.Unmarshal(raw, &resp); err != nil {
+		t.Fatalf("failed to parse output: %v\n%s", err, string(raw))
+	}
+	data, _ := resp["data"].(map[string]any)
+	minutes, _ := data["minutes"].([]any)
+	if len(minutes) != 1 {
+		t.Fatalf("expected 1 minute, got %d in %s", len(minutes), string(raw))
+	}
+	m, _ := minutes[0].(map[string]any)
+	return m
+}
+
 // chdirForDetailTest switches cwd to a temp dir for the test.
 func chdirForDetailTest(t *testing.T) string {
 	t.Helper()

shortcuts/minutes/minutes_upload.go

@@ -5,6 +5,8 @@ package minutes
 
 import (
 	"context"
+	"net/url"
+	"strings"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
@@ -65,8 +67,25 @@ var MinutesUpload = common.Shortcut{
 		outData := map[string]interface{}{
 			"minute_url": minuteURL,
 		}
+		if minuteToken := extractUploadedMinuteToken(minuteURL); minuteToken != "" {
+			outData["minute_token"] = minuteToken
+		}
 
 		runtime.OutFormat(outData, nil, nil)
 		return nil
 	},
 }
+
+func extractUploadedMinuteToken(minuteURL string) string {
+	u, err := url.Parse(minuteURL)
+	if err != nil {
+		return ""
+	}
+	parts := strings.Split(strings.TrimRight(u.Path, "/"), "/")
+	for i, part := range parts {
+		if part == "minutes" && i+1 < len(parts) {
+			return parts[i+1]
+		}
+	}
+	return ""
+}

shortcuts/minutes/minutes_upload_test.go

@@ -143,4 +143,28 @@ func TestMinutesUpload_Execute(t *testing.T) {
 	if dataMap["minute_url"] != "https://sample.feishu.cn/minutes/obcnq3b9jl72l83w4f149w9c" {
 		t.Errorf("expected minute_url https://sample.feishu.cn/minutes/obcnq3b9jl72l83w4f149w9c, got %v", dataMap["minute_url"])
 	}
+	if dataMap["minute_token"] != "obcnq3b9jl72l83w4f149w9c" {
+		t.Errorf("expected minute_token obcnq3b9jl72l83w4f149w9c, got %v", dataMap["minute_token"])
+	}
+}
+
+func TestExtractUploadedMinuteToken(t *testing.T) {
+	tests := []struct {
+		name string
+		url  string
+		want string
+	}{
+		{name: "standard", url: "https://sample.feishu.cn/minutes/obcnq3b9jl72l83w4f149w9c", want: "obcnq3b9jl72l83w4f149w9c"},
+		{name: "query", url: "https://sample.feishu.cn/minutes/obcn123?from=upload", want: "obcn123"},
+		{name: "trailing slash", url: "https://sample.feishu.cn/minutes/obcn123/", want: "obcn123"},
+		{name: "invalid", url: "://bad", want: ""},
+		{name: "no minutes path", url: "https://sample.feishu.cn/docx/abc", want: ""},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := extractUploadedMinuteToken(tt.url); got != tt.want {
+				t.Fatalf("extractUploadedMinuteToken(%q) = %q, want %q", tt.url, got, tt.want)
+			}
+		})
+	}
 }

shortcuts/register_test.go

@@ -170,6 +170,27 @@ func TestRegisterShortcutsMountsDocsMediaPreview(t *testing.T) {
 	}
 }
 
+func TestRegisterShortcutsMountsDocsHistoryCommands(t *testing.T) {
+	program := &cobra.Command{Use: "root"}
+	RegisterShortcuts(program, newRegisterTestFactory(t))
+
+	for _, name := range []string{"+history-list", "+history-revert", "+history-revert-status"} {
+		cmd, _, err := program.Find([]string{"docs", name})
+		if err != nil {
+			t.Fatalf("find docs %s shortcut: %v", name, err)
+		}
+		if cmd == nil || cmd.Name() != name {
+			t.Fatalf("docs %s shortcut not mounted: %#v", name, cmd)
+		}
+		if cmd.Flags().Lookup("api-version") != nil {
+			t.Fatalf("docs %s should not expose --api-version", name)
+		}
+		if !strings.Contains(cmd.Long, "lark-cli skills read lark-doc references/lark-doc-history.md") {
+			t.Fatalf("docs %s help missing history skill guidance:\n%s", name, cmd.Long)
+		}
+	}
+}
+
 func TestRegisterShortcutsDocsHelpAddsSkillReadGuidance(t *testing.T) {
 	program := &cobra.Command{Use: "root"}
 	RegisterShortcuts(program, newRegisterTestFactory(t))

skill-template/domains/drive.md

@@ -6,6 +6,7 @@
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
+- 批量执行 `drive +import` 且目标是同一个位置（同一 `--folder-token`、默认根目录，或同一 `--target-token`）时，必须串行执行；不要并发导入到同一位置，服务端可能返回并发冲突错误。
 - 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。
 - `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
 
@@ -194,6 +195,7 @@ lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "
 | `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
 | `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
 | `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides/bitable） |
+| `232140101` / `232140100` / `233523001`（常见于 `drive +import` 的 `job_error_msg`） | 同一位置下存在并发导入 / 创建操作 | 批量导入到同一文件夹、根目录或同一 `--target-token` 时改为串行执行；每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突 |
 
 ### 授权当前应用访问文档
 

skills/lark-calendar/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 
 开始前先读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)（认证、权限处理）。
 
-**CRITICAL — 凡涉及预约日程/会议或查询/搜索会议室，第一步 MUST 读 [`references/lark-calendar-schedule-meeting.md`](references/lark-calendar-schedule-meeting.md)。禁止跳过此步直接调用 API 或 Shortcut！**
+**CRITICAL — 凡涉及预约日程/会议室、调整时间或查询/搜索会议室，第一步 MUST 读 [`references/lark-calendar-schedule-meeting.md`](references/lark-calendar-schedule-meeting.md)。仅编辑字段（改标题/描述）或增删参会人（不涉及时间和会议室）时可跳过，直接读 [`references/lark-calendar-update.md`](references/lark-calendar-update.md)。**
 
 ## 身份
 
@@ -30,28 +30,84 @@ lark-cli calendar +agenda --as user
 
 | Shortcut | 说明 |
 |----------|------|
-| [`+agenda`](references/lark-calendar-agenda.md) | 查看日程安排（默认今天） |
-| [`+search-event`](references/lark-calendar-search-event.md) | 按关键词、时间范围和参会人搜索日程, 仅返回 日程ID/主题/时间等信息，详情需走 `events get` |
+| `+agenda` | 查看日程安排（默认今天） |
 | [`+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 状态 |
+| `+freebusy` | 查询用户主日历的忙闲信息和 RSVP 状态（纯查询场景；预约场景走 `+suggestion`） |
 | [`+room-find`](references/lark-calendar-room-find.md) | 针对一个或多个**明确的**时间块查找可用会议室（无明确时间时禁止直接调用，需先走 +suggestion） |
 | [`+rsvp`](references/lark-calendar-rsvp.md) | 回复日程（接受/拒绝/待定） |
 | [`+suggestion`](references/lark-calendar-suggestion.md) | 根据非明确时间或一段时间范围，推荐多个可用时间块方案 |
 
+### `+get` — 单日程详情
+
+通过 `calendar_id` + `event_id` 获取**单个日程**详情。
+
+```bash
+# calendar_id不传，默认primary
+lark-cli calendar +get --calendar-id <calendar_id> --event-id <event_id>
+```
+
+### `+search-event` — 按关键词、时间范围和参会人搜索日程
+
+仅返回基础字段（`event_id`/`summary`/`start`/`end` 等），需要详情请走 `+get`。
+
+```bash
+# query 按关键词 可选
+# start/end 按时间范围（ISO 8601 或 YYYY-MM-DD）可选
+# attendee-ids 按参会人（自动识别 ou_ 用户 / oc_ 群聊 / omm_ 会议室前缀）可选
+# page-token 分页游标，用于继续翻页 可选
+# page-size 每页数量，默认 30 可选
+lark-cli calendar +search-event --query "周会" --start 2026-04-20 --end 2026-04-27 --attendee-ids "ou_user1,oc_chat1,omm_room1" --page-token <page_token> --page-size 30
+```
+
+### `+agenda` — 查看近期日程安排
+
+默认查询当天。结果应整理为按日期分组、按开始时间升序的易读时间线。
+
+```bash
+# start/end 时间范围（ISO 8601 / YYYY-MM-DD / Unix 秒），均可选；默认当天
+# calendar-id 日历 ID（默认primary）可选
+lark-cli calendar +agenda --start 2026-03-10 --end 2026-03-17 --calendar-id <calendar_id>
+```
+
+注意：
+- 已取消的日程自动过滤；无日程时直接告知"日程清空"。
+- 时间范围超过 40 天会自动拆分查询并合并结果。
+
+### `+freebusy` — 查询主日历忙闲时段和 RSVP 状态
+
+仅返回忙碌时段起止时间，不含日程标题等隐私信息；其他订阅日历不在范围内。
+
+```bash
+# start/end 时间范围（ISO 8601 / YYYY-MM-DD / Unix 秒），均可选；默认当天
+# user-id 目标用户 open_id（ou_ 前缀）可选；默认当前登录用户，bot 身份必须显式指定
+lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
+```
+
+用法提示：
+- **仅判断是否有空** → `+freebusy`；**需要日程详情** → `+agenda`。
+- 检查多人可用性：分别调用并对比，找共同空闲。
+- 预约/改约场景下，调用规则（参与人过多、含群组、来自 `+suggestion` 等）详见 [schedule-clear-time.md § 查询忙闲](references/lark-calendar-schedule-clear-time.md#2-查询忙闲)。
+
 ## 前置条件路由
 
 | 场景 | 前置要求 |
 |------|----------|
-| 预约日程/会议、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) |
-| 编辑已有日程 | 先定位目标日程 `event_id`；若是重复性日程，必须定位到具体实例的 `event_id`（禁止使用原重复日程 ID） |
-| 删除/修改后验证 | 等待 2 秒再查询（API 最终一致性），不要告知用户你等待了 |
+| 预约日程/会议、调整时间、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) |
+| 仅编辑字段（标题/描述）或增删参会人 | 先定位 `event_id`，再读 [lark-calendar-update.md](references/lark-calendar-update.md) |
+| 编辑已有日程（涉及时间或会议室） | 先定位目标日程 `event_id`；若是重复性日程，必须定位到具体实例的 `event_id`（禁止使用原重复日程 ID） |
+| 编辑/删除重复性日程 | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，按操作范围（仅此次/全部/此次及后续）执行 |
 | 调用任何 Shortcut | 先读其对应 reference 文档 |
 
+## 写操作反馈
+
+创建、更新、删除、RSVP 等写操作完成后，直接基于命令返回结果反馈用户；不要为了“确认是否生效”主动发起二次查询。只有用户明确要求复查，或命令返回信息不足以回答用户问题时，才需要再查询。
+
 ## 核心概念
 
-- **日程实例（Instance）**：重复性日程展开后的具体时间实例。操作重复日程的某次实例时，必须先定位该实例的 `event_id`，禁止使用原重复日程的 `event_id`。
+- **日程实例（Instance）**：重复性日程展开后的具体时间实例。「仅此次」操作时使用具体实例的 `event_id`；「全部」或「此次及后续」操作时需对原重复性日程操作（使用原日程 `event_id`），并按需处理例外。
+- **重复性日程例外（Exception）**：对重复性日程某次实例做过「仅此次」编辑后产生的独立日程（拥有独立 `event_id`）。删除/更新「全部」时必须同时处理例外，否则例外会残留。
 - **全天日程（All-day Event）**：只按日期占用、没有具体起止时刻的日程，结束日期是包含在日程时间内的。
 - **时间块 vs 时间范围**：时间块是具体确定的连续时间段（如 `14:00~15:00`），时间范围是泛指（如"今天下午"）。`+room-find` 必须基于确定时间块，不能基于模糊范围。
 - **会议室（Room）**："room"不是"房间"，是"会议室"。会议室是日程的一种参与人（resource attendee），不能脱离日程单独预定。
@@ -70,7 +126,9 @@ lark-cli calendar +agenda --as user
 | 按关键词搜索日程 | 本 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) |
+| 预约/改约日程、调整时间、添加/更换会议室、查会议室 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) |
+| 仅编辑日程字段（标题/描述）或增删参会人（不涉及时间和会议室） | 先定位 `event_id`，再读 [+update](references/lark-calendar-update.md) 执行变更 |
+| 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，确认操作范围后执行 |
 
 ## 任务类型分流
 
@@ -87,7 +145,7 @@ lark-cli calendar +agenda --as user
 
 ## 会议室规则
 
-- 凡是"预定/查询/搜索可用会议室"，都必须进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md)。
+- 凡是"预定/查询/搜索可用会议室"，都必须进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md)，会议室参数规范详见 [+room-find](references/lark-calendar-room-find.md)。
 - `+room-find` 的时间输入必须是确定时间块，不能是时间区间搜索。
 - 用户仅要求"查会议室"但未提供明确时间时，必须先调用 `+suggestion` 获取可用时间块，再将时间块交给 `+room-find`。严禁猜测时间盲目调用。
 - 编辑已有日程时，"添加会议室"默认是增量语义，保留已有会议室；只有用户明确说"更换会议室""移除会议室"时才删除旧会议室。
@@ -95,42 +153,45 @@ lark-cli calendar +agenda --as user
 ## API Resources
 
 ```bash
+# 通用调用格式
 lark-cli calendar <resource> <method> [flags]
+
+# 查询用户主日历
+lark-cli calendar calendars primary
+
+# 获取日程分享链接
+lark-cli calendar events share_info --calendar-id <calendar_id> --event-id <event_id>
+
+# 删除日程
+lark-cli calendar events delete --calendar-id <calendar_id> --event-id <event_id>
 ```
 
-### calendars
+> `calendar_id` 可以直接传 `primary`，代表当前调用身份的主日历 ID。
 
-  - `create` — 创建共享日历
-  - `delete` — 删除共享日历
-  - `get` — 查询日历信息
-  - `list` — 查询日历列表
-  - `patch` — 更新日历信息
-  - `primary` — 查询用户主日历
-  - `search` — 搜索日历
+### 查询资源的方法列表以及方法的使用方式
 
-### event.attendees
+- 列出某资源下的方法：`lark-cli calendar <resource> -h`
+- 查看方法的cli flag：`lark-cli calendar <resource> <method> -h`
+- 查看方法API参数：`lark-cli schema calendar.<resource>.<method>`
 
-  - `batch_delete` — 删除日程参与人
-  - `create` — 添加日程参与人
-  - `list` — 获取日程参与人列表
+`<resource>` 为 `calendars`（日历本身）/ `events`（日程）/ `event.attendees`（参与人）/ `freebusys`（忙闲）。例：`lark-cli schema calendar.events.delete`。
 
-### events
+## 常用其他域命令
 
-  - `create` — 创建日程
-  - `delete` — 删除日程
-  - `get` — 获取日程
-  - `instance_view` — 查询日程视图
-  - `patch` — 更新日程
-  - `share_info` — 获取日程分享链接
+```bash
+# 搜索用户，更多参数详见 lark-contact
+lark-cli contact +search-user --query <query> --as user
 
-### freebusys
-
-  - `list` — 查询主日历日程忙闲信息
+# 搜索群聊，更多参数详见 lark-im
+lark-cli im +chat-search --query <query> --as user
+```
 
 ## 不在本 skill 范围
 
 - 查询过去的视频会议记录 → [lark-vc](../lark-vc/SKILL.md)
 - 待办任务管理 → [lark-task](../lark-task/SKILL.md)
+- 通讯录 → [lark-contact](../lark-contact/SKILL.md)
+- 即时通讯 → [lark-im](../lark-im/SKILL.md)
 - 会议室物理设施管理 → 管理员后台
 
 **注意（强制性）：**

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

@@ -1,78 +0,0 @@
-
-# calendar +agenda
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-查看近期日程安排。只读操作，不修改任何日程。
-
-需要的scopes: ["calendar:calendar.event:read"]
-
-## 命令
-
-```bash
-# 查看今天日程（默认）
-lark-cli calendar +agenda
-
-# 自定义时间范围（ISO 8601）
-lark-cli calendar +agenda --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00"
-
-# 自定义时间范围（仅日期）
-lark-cli calendar +agenda --start 2026-03-10 --end 2026-03-17
-
-# 人类可读格式输出
-lark-cli calendar +agenda --format pretty
-
-# 指定日历
-lark-cli calendar +agenda --calendar-id cal_xxx
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--start <time>` | 否 | 开始时间（ISO 8601 或仅日期，默认当天） |
-| `--end <time>` | 否 | 结束时间（默认与 `--start` 属于同一天，自动取当天结束时间） |
-| `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） |
-| `--format` | 否 | 输出格式：json（默认） \| pretty |
-| `--dry-run` | 否 | 预览 API 调用，不执行 |
-
-## 时间格式
-
-`--start` 和 `--end` 支持以下格式：
-
-| 格式 | 示例 | 说明 |
-|------|------|------|
-| ISO 8601 | `2026-03-10T14:00:00+08:00` | 完整格式 |
-| 日期+时间 | `2026-03-10 14:00:00` | 自动补全时区 |
-| 仅日期 | `2026-03-10` | start 取 00:00:00，end 取 23:59:59 |
-| Unix 时间戳 | `1741564800` | 秒级时间戳 |
-
-## 输出格式
-
-**将结果整理为易读的日程表：**
-
-```
-## 2026-03-10 周一
-
-09:00 - 09:30  站会
-10:00 - 11:00  产品评审
-14:00 - 15:00  与 Alice 1:1
-
-## 2026-03-11 周二
-
-（无日程）
-```
-
-**注意：按日期分组，并严格按照开始时间升序（从早到晚的时间线）排序输出。** 显示标题、时长
-
-## 提示
-
-- 已取消的日程会自动过滤，无需额外处理。
-- 如无日程，告知用户"日程清空"。
-- 大于 40 天的时间范围会自动拆分查询并合并结果。
-- 查看多个日历：先用 `lark-cli calendar calendars list --page-all` 列出日历列表，再逐个查询。
-
-## 参考
-
-- [lark-calendar](../SKILL.md) -- 日历全部命令
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -1,12 +1,9 @@
 
 # calendar +create
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 创建日程并按需邀请参会人。
 
-需要的scopes: ["calendar:calendar.event:create","calendar:calendar.event:update"]
-
 ## 推荐命令
 
 ```bash
@@ -38,15 +35,16 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 | `--description <text>` | 否 | 日程详细描述。提供会议议程、活动内容、注意事项或链接等。与 summary 配合使用，仅关注当前日程信息 |
 | `--attendee-ids <id_list>` | 否 | 参与人 ID 列表（逗号分隔）。支持用户（`ou_`）、群组（`oc_`）和会议室（`omm_`）。AI 提取时请务必保留对应前缀 |
 | `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） |
-| `--rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。**【⚠️注意：系统绝对不支持 COUNT，如需限制重复次数，必须转为 UNTIL】**。示例值："FREQ=DAILY;INTERVAL=1" |
+| `--rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。示例值："FREQ=DAILY;INTERVAL=1;UNTIL=<具体日期>" |
 | `--dry-run` | 否 | 预览 API 调用，不执行 |
 
-> **⚠️ `rrule` 规则限制：飞书日历系统不支持 `COUNT` 参数。遇到限制重复次数的需求，必须根据开始时间和频率自行推算并转换成 `UNTIL=<具体日期>` 格式。**
+> 当用户表达'每周 X'、'每周重复'、'连续 N 周'时，必须使用 rrule 创建重复性日程，而非创建多个独立日程
 > 自动设置 `attendee_ability: "can_modify_event"`，参会人可查看彼此并编辑日程。
 > 自动设置 `free_busy_status: "busy"`，默认日程忙闲状态为忙碌。
 > 自动设置 `reminders: [{"minutes": 5}]`，默认日程开始前 5 分钟提醒。
 > 自动设置 `vchat: {"vc_type": "vc"}`，默认日程包含飞书视频会议。如需其他视频会议类型或不含视频会议，请使用完整 API 命令。
 > 失败保护：若添加参会人失败（如 open_id 错误），CLI 会自动删除刚创建的空日程（回滚，不通知参会人）。
+> 审批会议室：`+create` 不暴露低频字段 `attendees[].approval_reason`。如果会议室要求审批，请使用用户身份先创建日程，再用完整 API `calendar event.attendees create --as user` 添加会议室并传 `approval_reason`。
 
 ## 高级用法（完整 API 命令）
 
@@ -55,37 +53,16 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 - 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天。如果只有一天的话，开始日期和结束日期是相同。
 
 ```bash
-# 第一步：创建日程（含高级参数）
-## 查看完整参数定义
-lark-cli schema calendar.events.create
-## 创建日程
-lark-cli calendar events create \
-  --params '{"calendar_id":"<CALENDAR_ID>"}' \
-  --data '{
-  "summary": "技术分享：CLI 架构设计",
-  "start_time": { "timestamp": "1741586400" },
-  "end_time": { "timestamp": "1741593600" }
-}'
-
-# 第二步：添加参会人（使用第一步返回的 calendar_id 和 event_id）
-## 查看完整参数定义
-lark-cli schema calendar.event.attendees.create
-## 添加参会人
+## 添加需要审批的会议室（approval_reason 最大 200 字符）
 lark-cli calendar event.attendees create \
+  --as user \
   --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
-  --data '{"attendees": [{"type": "user", "user_id": "ou_xxx"}]}'
+  --data '{"attendees": [{"type": "resource", "room_id": "omm_xxx", "approval_reason": "申请原因"}]}'
 
-# 可选第三步（推荐）：若第二步失败，回滚删除空日程
-## 查看完整参数定义
-lark-cli schema calendar.events.delete
-## 删除空日程
-lark-cli calendar events delete \
-  --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>","need_notification":false}'
-
-```
-
-> 完整 API 命令的时间参数是 **Unix 秒字符串**（非 ISO 8601）。
-> 当你手动拆成两步执行时，建议保留“失败后回滚删除”的第三步，避免遗留空日程。
+完整 API 命令的关键差异：
+- 时间参数是 **Unix 秒字符串**（非 ISO 8601）。
+- 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天；单日全天日程两者相同。
+- 手动拆成“创建日程 + 添加参会人”两步时，若第二步失败，建议删除刚创建的空日程，避免遗留无参会人的日程。
 
 ## 参会人类型
 
@@ -101,6 +78,5 @@ lark-cli calendar events delete \
 
 ## 参考
 
-- [lark-calendar](../SKILL.md) -- 日历全部命令
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [lark-calendar](../SKILL.md) -- skill 入口与路由
 - [lark-calendar-suggestion](lark-calendar-suggestion.md) -- 根据非明确时间或一段时间范围，推荐多个可用时间块方案

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

@@ -1,124 +0,0 @@
-
-# calendar +freebusy
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
-
-查询用户主日历的忙闲信息，返回指定时间范围内的忙碌时段列表和rsvp的状态。
-
-需要的scopes: ["calendar:calendar.free_busy:read"]
-
-## 命令
-
-```bash
-# 查询当前用户今天的忙闲（默认）
-lark-cli calendar +freebusy
-
-# 自定义时间范围（仅日期）
-lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12
-
-# 自定义时间范围（完整 ISO 8601）
-lark-cli calendar +freebusy --start "2026-03-11T08:00:00+08:00" --end "2026-03-11T18:00:00+08:00"
-
-# 查询指定用户的忙闲信息
-lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx
-
-# 人类可读格式输出
-lark-cli calendar +freebusy --format pretty
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--start <time>` | 否 | 查询开始时间（ISO 8601 或仅日期，默认当天） |
-| `--end <time>` | 否 | 查询结束时间（默认与 `--start` 属于同一天，自动取当天结束时间） |
-| `--user-id <open_id>` | 否 | 目标查询用户 ID（`ou_` 前缀）。省略时默认查询当前登录用户，bot 身份调用时必须明确指定 |
-| `--format` | 否 | 输出格式：json（默认） \| pretty |
-| `--dry-run` | 否 | 预览 API 调用，不执行 |
-
-## 时间格式
-
-`--start` 和 `--end` 支持以下格式：
-
-| 格式 | 示例 | 说明 |
-|------|------|------|
-| ISO 8601 | `2026-03-11T09:00:00+08:00` | 完整格式 |
-| 日期+时间 | `2026-03-11 09:00:00` | 自动补全时区 |
-| 仅日期 | `2026-03-11` | start 取 00:00:00，end 取 23:59:59 |
-| Unix 时间戳 | `1741564800` | 秒级时间戳 |
-
-## 输出示例
-
-### 表格格式
-
-```
-start             end               rsvp_status
-----------------  ----------------  -----------
-2026-03-11 10:00  2026-03-11 10:30  接受
-2026-03-11 14:00  2026-03-11 15:00  待定
-
-共 2 个忙碌时段
-```
-
-### JSON 格式
-
-```json
-[
-  {
-    "start_time": "2026-03-11T10:00:00+08:00",
-    "end_time": "2026-03-11T10:30:00+08:00",
-    "rsvp_status": "accept"
-  },
-  {
-    "start_time": "2026-03-11T14:00:00+08:00",
-    "end_time": "2026-03-11T15:00:00+08:00",
-    "rsvp_status": "tentative"
-  }
-]
-```
-
-## 典型场景
-
-### 1. 查找日程会议空闲时段
-
-```bash
-# 查询今天的忙碌时段
-lark-cli calendar +freebusy
-
-# 查询工作时间段
-lark-cli calendar +freebusy \
-  --start "2026-03-11T08:00:00+08:00" \
-  --end "2026-03-11T18:00:00+08:00"
-```
-
-### 2. 检查团队成员可用性
-
-```bash
-# 查询多个成员，对比找出共同空闲时间
-lark-cli calendar +freebusy --start 2026-03-12 --user-id ou_member_a
-lark-cli calendar +freebusy --start 2026-03-12 --user-id ou_member_b
-```
-
-## 注意事项
-
-1. **只查询主日历** — 此命令只返回用户主日历的忙闲信息，不包括其他订阅日历
-2. **隐私保护** — 只返回忙碌时段的起止时间，不包含日程标题、描述等详细信息
-3. **bot 身份** — bot 必须通过 `--user-id` 指定要查询的用户
-
-## 与其他命令对比
-
-| 命令 | 用途 | 输出内容 |
-|------|------|----------|
-| `calendar +freebusy` | 查询忙闲时段 | 只返回忙碌时段列表（无日程详情） |
-| `calendar +agenda` | 查看日程安排 | 返回完整日程列表（含标题、描述等） |
-
-**选择建议**：
-- **仅需了解是否有空** → 使用 `+freebusy`（更快，隐私保护）
-- **需要查看日程详情** → 使用 `+agenda`
-
-## 参考
-
-- [lark-calendar-agenda](lark-calendar-agenda.md) — 查看日程安排
-- [lark-calendar-create](lark-calendar-create.md) — 创建日程
-- [lark-calendar-suggestion](lark-calendar-suggestion.md) — 根据非明确时间或一段时间范围，推荐多个可用时间块方案
-- [lark-calendar](../SKILL.md) — 日历完整 API

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

@@ -0,0 +1,90 @@
+# 重复性日程操作规范
+
+重复性日程的编辑/删除分为三种范围：「仅此次」「全部」「此次及后续」。用户未明确范围时，**必须询问确认**。
+
+## 关键概念
+
+- **event_id 结构**：`event_id` 的格式为 `{event_uid}_{originalTime}`。普通日程或重复性日程本体的 `originalTime` 为 `0`；例外的 `originalTime > 0`，代表该例外在原重复性序列中本来的时间位置。因此 `{event_uid}_0` 即为原重复性日程的 `event_id`。
+- **原重复性日程**：携带 `rrule` 的日程本体，`event_id` 形如 `{event_uid}_0`。系列的所有属性（标题、时间、rrule、描述等）都挂在本体上。
+- **例外（Exception）**：对某次实例做过「仅此次」编辑后产生的独立日程，`event_id` 形如 `{event_uid}_{originalTime}`（`originalTime > 0`）。通过 `event_uid` 部分即可关联回原重复性日程。
+- 删除/更新原重复性日程 **不会** 级联处理例外——必须手动逐个处理。
+
+## 前置步骤（所有范围通用）
+
+1. 通过 `+agenda` 或 `+search-event` 定位重复性日程，获取原重复性日程的 `event_id`。
+2. 通过 `events instance_view` 或 `+agenda` 列出实例，识别哪些是例外（`event_id` 中 `originalTime > 0` 的即为例外）。
+3. 确认用户的操作范围。
+
+## 编辑全部（更新时间）
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --start ... --end ...` | 更新原重复性日程的时间 |
+| 2 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<例外ID>","need_notification":false}'` （逐个） | 时间变更后例外已无意义，必须删除 |
+
+> 理由：更新时间会改变重复起止点，例外日程的原始占位已变，若保留会导致时间冲突或残留。
+
+## 编辑全部（更新非时间字段）
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --summary ... --description ...` | 更新原重复性日程的标题/描述等 |
+| 2 | `lark-cli calendar +update --event-id <例外ID> --summary ... --description ...` （逐个） | 同步更新例外日程的对应字段 |
+
+> 理由：例外已脱离原重复性日程独立存在，不会自动继承原日程的更新。
+
+## 删除全部
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<原重复日程ID>","need_notification":true}'` | 删除重复性日程本体 |
+| 2 | `lark-cli calendar events delete --params '{"calendar_id":"<CAL_ID>","event_id":"<例外ID>","need_notification":false}'` （逐个） | 删除所有例外日程 |
+
+> 理由：例外是独立实体，删除原重复性日程不会级联删除例外。
+
+## 编辑此次及后续
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --rrule "FREQ=...;UNTIL=<截止日期>"` | 截短原重复性日程（UNTIL 设为指定时间前一次实例的日期） |
+| 2 | `lark-cli calendar events delete ...` （逐个） | 删除指定时间之后（含）的例外日程 |
+| 3 | `lark-cli calendar +create --summary ... --start <指定时间> --end ... --rrule "FREQ=..." --attendee-ids ...` | 从指定时间开始创建新的重复性日程（即「后续」部分，携带编辑后的内容） |
+
+> UNTIL 计算规则：若用户选择「从第 N 次开始编辑」，UNTIL 应设置为第 N-1 次实例的日期（即保留到指定时间之前的最后一次）。
+> 新日程应继承原日程的参会人、会议室等配置（除非用户明确要修改）。
+
+## 删除此次及后续
+
+| 步骤 | 命令 | 说明 |
+|------|------|------|
+| 1 | `lark-cli calendar +update --event-id <原重复日程ID> --rrule "FREQ=...;UNTIL=<截止日期>"` | 截短原重复性日程（UNTIL 设为指定时间前一次实例的日期） |
+| 2 | `lark-cli calendar events delete ...` （逐个） | 删除指定时间之后（含）的例外日程 |
+
+> 与「编辑此次及后续」的区别：不需要步骤 3（创建新的重复性日程），因为目标是删除后续而非替换。
+
+## 仅此次
+
+- **编辑仅此次**：通过 `+agenda` / `+search-event` 定位到具体实例的 `event_id`，然后正常调用 `+update`。
+- **删除仅此次**：定位到具体实例的 `event_id`，调用 `events delete`。
+
+## 用户意图映射
+
+| 用户表达 | 操作范围 |
+|----------|----------|
+| 「改这个重复日程的标题」「全部改」「每次都改」 | 编辑全部 |
+| 「删掉这个重复日程」「取消所有」 | 删除全部 |
+| 「从下周开始改时间」「后面的都改」 | 编辑此次及后续 |
+| 「从下周开始不要了」「后面的都删」 | 删除此次及后续 |
+| 「就改这一次」「只删这一次」 | 仅此次 |
+| 未明确范围 | **必须询问用户** |
+
+## 注意事项
+
+- 涉及时间戳计算（如推算 UNTIL 日期）时，必须调用系统命令或脚本，禁止心算。
+
+## 参考
+
+- [lark-calendar](../SKILL.md) — 日历全部命令
+- [lark-calendar-update](lark-calendar-update.md) — 更新日程 Shortcut
+- [lark-calendar-create](lark-calendar-create.md) — 创建日程 Shortcut
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-calendar/references/lark-calendar-room-find.md

@@ -1,11 +1,8 @@
 # calendar +room-find
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
 
 针对一个或多个时间块查找/搜索可用会议室。会议室是日程的一种资源型参与人，不能脱离日程单独预定。
 
-需要的 scopes: ["calendar:calendar.free_busy:read"]
-
 ## 适用场景
 
 - 已知一个或多个待选时间块，需要查找可用会议室
@@ -50,7 +47,7 @@ lark-cli calendar +room-find \
 | `--city <text>` | 否 | 会议室所在城市强约束。**仅当**用户明确说出具体城市（如北京、上海）时才提取，**严禁**根据园区或楼宇名称自行联想或补全。 |
 | `--building <text>` | 否 | 会议室所在楼宇强约束，承载城市以下、楼层以上的办公区/园区/楼栋描述。|
 | `--floor <text>` | 否 | 仅用于筛选会议室所在楼层。应先做归一化，再传递规范值；例如 `2楼` / `二楼` / `2F` 统一为 `F2`。注意：此参数只筛选楼层，不可混入区域定位（如“A区”）或具体会议室号。 |
-| `--room-name <text>` | 否 | 会议室名称约束，支持以**英文逗号**分隔传入多个名称。仅当用户明确提到会议室专名或会议室号（如"木星""02"）时使用。当用户需要在一组编号会议室中搜索时（如"帮我约 16~20 号的会议室"），应将编号展开为逗号分隔列表，如 `"16,17,18,19,20"`。应优先传递去后缀、去冗余后的规范名，例如 `木星会议室` → `木星`，`会议室 02` / `02会议室` → `02`。 |
+| `--room-name <text>` | 否 | 会议室名称约束，支持以**英文逗号**分隔传入多个名称。仅当用户明确提到会议室专名、会议室号或编号区间时使用。 |
 | `--min-capacity <n>` | 否 | 会议室最小容纳人数。当用户明确参会人数或提出“至少容纳N人”等要求时，提取数字放入此参数，必须为正整数。 |
 | `--max-capacity <n>` | 否 | 会议室最大容纳人数。用于过滤过大空间，必须为正整数。 |
 | `--attendee-ids <id_list>` | 否 | 参会对象 ID 列表。支持用户 ID（`ou_` 前缀）和群组 ID（`oc_` 前缀），多个 ID 以逗号分隔。 |
@@ -67,7 +64,7 @@ lark-cli calendar +room-find \
 - 同一语义槽位只保留一个规范值。例如用户说“2楼”，应转换为 `--floor "F2"`；**禁止**同时传 `2楼 F2` 这类重复楼层信息。
 - 参数归类顺序应为：`city/building/floor` > `floor + room-name` 复合表达 > `room-name`。若短词更像楼层/区域定位（如 `2L`、`2F`），优先落到 `--floor`，不要默认落到 `--room-name`。像 `学清2层` 这种表达，通常拆为 `--building "学清"` 与 `--floor "F2"`。
 - 对会议室名要做轻量归一化：`木星会议室` 应提取为 `--room-name "木星"`；`会议室 02` / `02会议室` 应提取为 `--room-name "02"`。
-- **多会议室名称场景**：当用户表达"帮我约 XX 到 YY 号之间的会议室"或一次提及多个会议室名称时，应将所有目标名称用英文逗号拼接传入 `--room-name`。例如：
+- 当用户表达"帮我约 XX 到 YY 号之间的会议室"或一次提及多个会议室名称时，应将所有目标名称用英文逗号拼接传入 `--room-name`。例如：
   - "帮我约 16~20 号的会议室" → `--room-name "16,17,18,19,20"`
   - "查下木星和火星是否有空" → `--room-name "木星,火星"`
   - "看看 01、02、03 会议室" → `--room-name "01,02,03"`
@@ -90,9 +87,8 @@ lark-cli calendar +room-find \
 ```
 
 > **AI 行为指导：**
-> - **结构化展示时间块与会议室**：默认按“时间块 -> 会议室候选”的层级结构展示。**严禁将时间与会议室名称输出在同一行**。以清晰的分行列表呈现可用会议室，并直接询问用户意向。默认原样展示完整 `room_name`；不要擅自缩写、截断、改写，或仅提取楼层及会议室号替代完整名称。
+> - **结构化展示时间块与会议室**：默认按“时间块 -> 会议室候选”的层级结构展示，并直接询问用户意向。
 > - **`room_name` 必须逐字透传**：展示给用户的会议室名称，必须直接使用 CLI/API 返回的 `room_name` 原值。禁止提取楼层、会议室号、容量、视频能力后重组成新的名称，禁止意译、缩写、去前缀、去后缀，或仅保留"便于阅读"的摘要名。
-> - **主动识别区间/多名称意图**：当用户提到"帮我约 XX 到 YY 号的会议室""XX~YY 之间的会议室"或一次列出多个会议室名称时，将所有目标名称展开为英文逗号分隔列表，传入 `--room-name`。例如"帮我约 16 到 20 号的会议室"应生成 `--room-name "16,17,18,19,20"`。
 > - **重复日程要明确阻断原因与自动缩短**：若某候选会议室的 `reserve_until_time` 无法覆盖重复性日程，**必须**向用户明确说明该会议室最长可约至何时。若用户确认继续选用该会议室，你必须**自动将日程的重复规则结束时间缩短**至该 `reserve_until_time`，以防止会议室预约失败。不能直接按原规则继续。
 > - **正确解释推荐结果**：如果返回结果与用户输入条件不完全字面一致，先说明底层可能返回邻近位置或相近条件的推荐候选，不要直接将其判定为异常。
 > - **默认减少用户输入成本**：应主动引导用户不必一开始就提供很详细的会议室搜索条件。只要时间块已明确，用户直接表达“想约会议室”即可，先基于当前信息查询候选；只有在用户对结果不满意时，再引导其补充更具体的楼宇、楼层、会议室名或容量条件。
@@ -102,7 +98,7 @@ lark-cli calendar +room-find \
 | 字段名 | 说明 |
 | :--- | :--- |
 | `room_id` | 会议室唯一标识，用于后续创建日程时添加为会议室参与人使用。 |
-| `room_name` | 会议室名称，默认原样完整展示给用户，不要自行缩写、截断、改写，也不要用楼层及会议室号摘要替代原值。 |
+| `room_name` | 会议室名称，展示给用户时必须使用原值。 |
 | `capacity` | 会议室最大容纳人数。 |
 | `reserve_until_time` | 该会议室当前允许被预约到的最晚时间点，用于校验重复性日程是否超期。 |
 
@@ -110,4 +106,4 @@ lark-cli calendar +room-find \
 
 - [lark-calendar-create](lark-calendar-create.md)
 - [lark-calendar-suggestion](lark-calendar-suggestion.md)
-- [lark-calendar](../SKILL.md) — 日历完整 API
+- [lark-calendar](../SKILL.md) — skill 入口与路由

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

@@ -1,11 +1,8 @@
 # calendar +rsvp
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 回复指定的日程，更新当前用户的 RSVP 状态（接受、拒绝或待定）。
 
-需要的scopes: ["calendar:calendar.event:reply"]
-
 ## 命令
 
 ```bash
@@ -38,5 +35,4 @@ lark-cli calendar +rsvp --calendar-id cal_xxx --event-id evt_xxx --rsvp-status a
 
 ## 参考
 
-- [lark-calendar](../SKILL.md) -- 日历全部命令
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [lark-calendar](../SKILL.md) -- skill 入口与路由

skills/lark-calendar/references/lark-calendar-schedule-clear-time.md

@@ -0,0 +1,59 @@
+# 明确时间分支：room-find + freebusy + 冲突处理
+
+> 本文档处理**时间已明确**的场景。"明确时间"来源：用户直接表达（如"明天下午3点"）、编辑流中已定位日程的原始 start/end、或经用户确认的 suggestion 时间块。
+
+## 前置条件
+
+进入此分支前，调度器（[schedule-meeting.md](./lark-calendar-schedule-meeting.md)）已完成：
+- 任务类型判定（新建 / 编辑）
+- 编辑流：目标 event_id 已定位
+- 新建流：默认值已补全
+- 时间已判定为**明确**
+
+## 流程
+
+### 1. 查询会议室（如需）
+
+若用户需要会议室，先调用 `+room-find`。详见 [`lark-calendar-room-find.md`](./lark-calendar-room-find.md)。
+
+```bash
+lark-cli calendar +room-find \
+  --slot "<start>~<end>" \
+  --attendee-ids "<ids>" \
+  --city "<city>" \
+  --building "<building>" \
+  --floor "<F2>" \
+  --room-name "<room_name>"
+```
+
+时间块确定规则：
+- **编辑流且不改时间，只新增会议室**：`--slot` 必须来自已定位日程的当前 `start/end`
+- **编辑流且既改时间又加会议室**：`--slot` 必须来自候选新时间，而不是旧时间
+
+详见 [`lark-calendar-room-find.md`](./lark-calendar-room-find.md)。
+
+### 2. 查询忙闲
+
+```bash
+lark-cli calendar +freebusy --start "<start>" --end "<end>"
+```
+
+规则：
+- 参与人过多（超过 5 人）：仅查询**当前用户**及少数核心人员忙闲即可
+- 参与人含**群组**：无需展开群组成员查询忙闲
+- 如果用户是从 `+suggestion` 确认了时间块后进入本分支的，**无需再调用 `+freebusy`**
+
+### 3. 冲突处理
+
+- **无冲突**：直接让用户选择会议室（如需），进入落地操作
+- **有冲突**：必须先说明冲突情况，询问用户：
+  - **继续当前时间** → 让用户选择会议室（如需），进入落地操作
+  - **换时间** → 转入 [模糊时间分支](./lark-calendar-schedule-fuzzy-time.md)
+
+## 落地
+
+根据任务类型：
+- 新建 → [`+create`](./lark-calendar-create.md)
+- 编辑 → [`+update`](./lark-calendar-update.md)
+
+落地规则详见 [schedule-meeting.md § 落地日程变更](./lark-calendar-schedule-meeting.md#落地日程变更)。

skills/lark-calendar/references/lark-calendar-schedule-fuzzy-time.md

@@ -0,0 +1,88 @@
+# 模糊时间 / 无时间信息分支：suggestion + 批量查询
+
+> 本文档处理**时间模糊**（如"明天下午""下周找个时间"）或**完全无时间信息**的场景。核心动作是调用 `+suggestion` 产出候选时间块，再根据是否需要会议室决定后续步骤。
+
+## 前置条件
+
+进入此分支前，调度器（[schedule-meeting.md](./lark-calendar-schedule-meeting.md)）已完成：
+- 任务类型判定（新建 / 编辑）
+- 编辑流：目标 event_id 已定位
+- 新建流：默认值已补全
+- 时间已判定为**模糊**或**无时间信息**
+
+## 流程
+
+### 1. 调用 suggestion
+
+详见 [`lark-calendar-suggestion.md`](./lark-calendar-suggestion.md)。
+
+```bash
+lark-cli calendar +suggestion \
+  --start "<range_start>" \
+  --end "<range_end>" \
+  --attendee-ids "<ids>" \
+  --duration-minutes <n> \
+  --event-rrule "<rrule>"
+```
+
+规则：
+- 用户完全没有提供时间信息时，先默认一个合理区间（如"今天剩余时间"或"近两天"）再调用
+- 编辑流中，若用户说"改到明天下午""下周找个时间再约"，基于用户期望的**新时间范围**调用，不要沿用旧时间
+- **不要在用户完全没给时间时反问"你想约什么时候"** — 先补合理区间再进入 suggestion
+
+### 2. 分支处理
+
+#### 不需要会议室
+
+获取多个推荐时间块后，直接向用户展示候选时间，用户确认后进入落地操作。
+
+#### 需要会议室
+
+获取候选时间块后，**不要急于让用户只选时间**。先将这些时间块一次性交给 `+room-find` 批量查询可用会议室，然后将【候选时间】与【对应的可用会议室列表】结构化展示，让用户一次性完成选择。
+
+> **注意**：即使用户最初只说"查会议室"且未带时间，也必须强制走 suggestion → room-find 路径。
+
+详见 [`lark-calendar-room-find.md`](./lark-calendar-room-find.md)。
+
+### 3. 用户确认后
+
+- 用户选中 `+suggestion` 返回的时间块后，**无需再次调用 `+freebusy`**，直接进入落地操作
+- **BLOCKING REQUIREMENT**：必须先向用户展示选项并等待确认，禁止在未获用户确认时直接创建/更新日程
+
+## 模糊语义消解与长期记忆
+
+针对存在歧义的时间场景，严禁主观臆断。典型例子：
+- "上班后" / "下班前"
+- 未明确上下午的 12 小时制时间
+
+处理规则：
+- 主动澄清真实意图，不自行猜测
+- 用户澄清后，将个性化定义沉淀为长期偏好
+
+## 用户展示格式
+
+向用户展示多个时间块及对应会议室时，**必须结构化分行排版**，严禁将时间与会议室放在同一行：
+
+```text
+## 2026-03-27 周五
+
+[选项 1] 14:00 - 15:00（参会人均空闲）
+  可用会议室：
+  1. 学清嘉创大厦B座-F2-02🎦(7人)
+  2. 学清嘉创大厦B座-F2-05🎦(10人)
+
+[选项 2] 16:00 - 17:00（参会人均空闲）
+  可用会议室：
+  1. 学清嘉创大厦B座-F3-01🎦(6人)
+  2. 学清嘉创大厦B座-F3-06🎦(8人)
+
+💡 请回复您倾向的选项编号以及对应的会议室序号，我来为您完成预定。
+```
+
+## 落地
+
+根据任务类型：
+- 新建 → [`+create`](./lark-calendar-create.md)
+- 编辑 → [`+update`](./lark-calendar-update.md)
+
+落地规则详见 [schedule-meeting.md § 落地日程变更](./lark-calendar-schedule-meeting.md#落地日程变更)。

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

@@ -1,206 +1,95 @@
 # 预约/改约日程或会议、查询/搜索可用会议室的工作流
 
-## CRITICAL 执行摘要（先按这个骨架执行，再看下方细则）
+## 执行摘要
 
-- **第一步永远是判断任务类型：新建日程，还是编辑已有日程。** 不要把“预约/查会议室”默认等同于“新建”。
-- **编辑已有日程时，必须先定位目标日程或实例的 `event_id`。** 用户一旦给出了既有日程锚点（标题、时间段、`这个日程`、`这场会`）并表达修改动作（加人、删人、改时间、换会议室等），默认走编辑流。
-- **默认做智能助理，不做表单填写机。** 能根据上下文补全的默认值就直接补全，避免把用户带入表单式问答。
-- **新建流先补默认值，编辑流先继承已定位日程信息。** 默认值包括标题、参会人、时长，以及在“完全无时间信息”时的默认时间范围；编辑流则优先复用已定位日程的标题、时间、已有参与人和会议室信息作为基线。
-- **只有三类场景才主动追问用户**：存在时间冲突、搜索结果无法唯一确定、时间语义本身有歧义。
-- **编辑流的时间基准必须明确。** 如果编辑时不改时间，则后续会议室搜索必须基于已定位日程的原始起止时间；如果既改时间又加会议室，必须先确定最终时间，再基于该时间搜索会议室。
-- **编辑流中“新增会议室”默认是增量语义。** 如果用户说的是“加会议室/再加一个会议室”，最终 `+update` 只做 `add`，默认保留已有会议室；只有在用户明确说“更换会议室/移除会议室”时，才执行旧会议室删除。
-- **明确时间**：若需要会议室，先 `+room-find`；再 `+freebusy` 判断参会人忙闲；有冲突时先说明冲突，再让用户决定继续当前时间还是改走 `+suggestion`。
-- **模糊时间或无时间信息**：先 `+suggestion` 产出候选时间块；若需要会议室，再把这些时间块批量交给 `+room-find`，将“候选时间 + 对应可用会议室”一次性展示给用户选择。
-- **BLOCKING REQUIREMENT: 只要面临时间方案（模糊时间/无时间）或会议室方案（需要会议室）的选择，必须先向用户展示选项并等待用户明确确认，绝对禁止在未获用户确认的情况下直接执行创建新日程或更新既有日程。**
-- **用户选中了 `+suggestion` 返回的候选时间块后，不要再次调用 `+freebusy`。** 用户确认后直接进入最终落地操作：创建新日程，或更新既有日程。
-- **当用户说“查会议室”“找会议室”“搜可用会议室”时，默认意图是查会议室可用性，不是检索会议室资源名录。**
-- **必须按顺序执行。** 不要跳过“任务类型判定”“目标日程定位（编辑流）”“补默认值/继承基线信息”“判断时间明确性”这些前置步骤。
-
-> **💡 核心原则：做智能助理，充分利用默认值规则（如默认标题、时长、参与人等）自动补全信息。极力避免像“表单填写机”一样频繁打断并反问用户，仅在必须决策的冲突或无法唯一确定的场景下才发起询问。**
+- **第一步永远是判断任务类型：新建日程，还是编辑已有日程。**
+- **编辑已有日程时，必须先定位目标日程或实例的 `event_id`。**
+- **默认做智能助理，不做表单填写机。** 能根据上下文补全的默认值就直接补全，仅在必须决策的冲突或无法唯一确定的场景下才发起询问。
+- **新建流先补默认值，编辑流先继承已定位日程信息。**
+- **明确时间** → 进入 [明确时间分支](./lark-calendar-schedule-clear-time.md)
+- **模糊时间或无时间信息** → 进入 [模糊时间分支](./lark-calendar-schedule-fuzzy-time.md)
+- **BLOCKING REQUIREMENT**: 面临时间方案或会议室方案的选择时，必须先向用户展示选项并等待确认，禁止未经确认直接创建/更新日程。
+- **必须按顺序执行。** 不要跳过"任务类型判定""目标日程定位（编辑流）""补默认值/继承基线信息""判断时间明确性"这些前置步骤。
 
 ## 严禁行为
 
-- **严禁在未读取对应子命令文档（如 `lark-calendar-room-find.md`、`lark-calendar-suggestion.md`）的情况下直接调用命令！** 必须先阅读文档掌握最新参数要求与规范。
-- **严禁在尚未判断“新建”还是“编辑”之前，就直接进入创建日程或查会议室动作。**
-- **严禁把“给明天上午的‘产品发布会’加人/加群/加会议室”这类带有既有日程锚点 + 修改动词的请求，当成新建日程。** 这类请求必须先定位目标日程。
-- **严禁在编辑已有日程时跳过目标定位步骤。** 未拿到唯一的 `event_id` 前，不得调用 `+update`、也不得基于猜测时间去查会议室。
-- **严禁在用户仅要求“查会议室”但未提供明确时间时，直接调用 `+room-find`！** 必须先默认一个合理时间范围，调用 `+suggestion` 拿到候选时间块，再将时间块传给 `+room-find`。
-- **不要在用户完全没给时间时，直接反问“你想约什么时候”。** 先补一个合理时间范围，再进入 `+suggestion`。
-- **不要在“需要会议室 + 时间模糊”的场景下，先让用户只选时间。** 应先批量查出每个候选时间对应的可用会议室，再让用户一次性完成选择。
-- **不要在用户已经选中 `+suggestion` 候选时间后，再重复调用 `+freebusy`。**
-- **不要在用户未明确说出城市时，仅凭园区/办公室名自动补城市。**
-- **严禁在面临时间方案或会议室方案的选择时（模糊时间、无时间或需要会议室），未经用户确认就擅自创建新日程或更新既有日程。**
+- **严禁在未读取对应子命令文档前直接调用命令。**
+- **严禁在尚未判断"新建"还是"编辑"之前，就直接进入创建日程或查会议室动作。**
+- **严禁把带有既有日程锚点 + 修改动词的请求当成新建日程。**
+- **严禁在编辑已有日程时跳过目标定位步骤。** 未拿到唯一 `event_id` 前，不得调用 `+update`。
+- **严禁在面临时间/会议室方案选择时，未经用户确认就擅自创建/更新日程。**
 
 ## 适用场景
 
-- “帮我约个会”
-- “下周找时间和 XX 开会”
-- “帮我订个会议室”
-- “帮我找/搜索一个可用的会议室”
-- “帮我推荐一个我以前常用的会议室”
-- “查询明天下午可用的会议室”
-- “明天下午3点约个日程/日历”
-- “把明天上午的日程‘产品发布会’加上 小明
-- “给下周一的周会换个会议室”
-- “把这个日程改到明天下午，并加上学清 F201”
+- "帮我约个会" / "下周找时间和 XX 开会"
+- "帮我订/找/搜索一个可用会议室"
+- "明天下午3点约个日程"
+- "把明天上午的日程加上 小明"
+- "给下周一的周会换个会议室"
+- "把这个日程改到明天下午，并加上学清 F201"
 
 ## 核心概念
 
-- **会议室是日程的一种参与人（attendee / resource），不能脱离日程单独预定。** 
-- **预定或查找会议室，均需先确定时间块。** 在推荐可用会议室后，应顺势引导用户完成最终的**日程落地**操作：创建新日程，或更新既有日程。
-
-## CRITICAL 约束
-
-- **在调用任何具体的 CLI 子命令（如 `+room-find`、`+suggestion`、`+freebusy`、`+create`）前，必须先读取其对应的 Markdown 文档。** 禁止仅凭记忆组装命令参数，以确保符合各命令最新的业务约束和格式规范。
-- **当用户说“查会议室”“找会议室”“搜可用会议室”等，默认意图是查询会议室可用性，而不是检索会议室资源名录。**
-- **必须严格按照下方【工作流】的步骤顺序完成任务。特别是单独查会议室时，若无明确时间，强制先走“模糊时间/无时间信息”分支调用 `+suggestion`。**
+- **会议室是日程的一种参与人（attendee / resource），不能脱离日程单独预定。**
+- **预定或查找会议室，均需先确定时间块。**
+- **当用户说"查会议室""找会议室"，默认意图是查会议室可用性，不是检索会议室资源名录。**
 
 ## 任务类型判定
 
 | 类型 | 典型语言信号 | 第一动作 |
 |------|--------------|----------|
-| 新建日程 | “约个会”“安排一个会议”“新建日程”“帮我订个会议室开会” | 补默认值，再进入时间判断 |
-| 编辑已有日程 | “给某个日程加人/删人/加群/加会议室”“把某个日程改到…”“给这场会换个会议室” | 先定位目标日程 `event_id`，再进入后续流程 |
+| 新建日程 | "约个会""安排会议""新建日程""订个会议室开会" | 补默认值，再进入时间判断 |
+| 编辑已有日程 | "给某日程加人/删人/加会议室""把某日程改到…""换会议室" | 先定位目标 `event_id` |
 
-进一步规则：
+规则：
+- 只要同时出现**既有日程锚点**（标题、时间段、`这个日程`、`这场会`）和**修改动词**（添加、移除、改到、换），默认判定为编辑。
+- 对重复性日程的编辑，必须先定位到对应实例的 `event_id`。
 
-- 只要同时出现**既有日程锚点**（标题、时间段、`这个日程`、`这场会`、某次实例）和**修改动词**（添加、移除、调整、改到、换、延后、提前），默认判定为**编辑已有日程**。
-- 对重复性日程的编辑，必须先定位到对应实例的 `event_id`，不能直接拿原重复日程的 `event_id` 做更新。
-
-## 工作流
-
-### 1. 编辑已有日程：先定位目标日程
-
-一旦判定为编辑流，必须先定位目标日程；没有 `event_id` 就不能继续后续修改动作。
+## 编辑流：先定位目标日程
 
 定位规则：
+- 优先利用用户给出的标题、日期、时间范围等锚点，通过 `+agenda`、`+search-event` 或实例视图缩小范围
+- 命中多个候选日程时，必须向用户展示候选项并要求确认
+- 重复性日程必须继续定位到该次实例的 `event_id`
 
-- 优先利用用户给出的标题、日期、时间范围、`这个日程/这场会` 等锚点，通过 `+agenda`、`+search-event` 或实例视图缩小范围。
-- 如果命中多个候选日程，必须向用户展示候选项并要求确认，禁止自行猜测。
-- 如果是重复性日程的某一次实例，必须继续定位到该次实例的 `event_id`。
+编辑流分支路由：
 
-编辑流分支规则：
+| 编辑子场景 | 下一步 |
+|-----------|--------|
+| 仅增删普通参会人/群组，不改时间，不涉及会议室 | 直接 `+update`（详见 [lark-calendar-update.md](./lark-calendar-update.md)） |
+| 新增会议室，不改时间 | 基于已定位日程 start/end → [明确时间分支](./lark-calendar-schedule-clear-time.md) |
+| 只改时间，不涉及会议室 | 判断时间明确性 → 对应分支 |
+| 既改时间，又新增/更换会议室 | 先确定最终时间 → 再查会议室 → 落地 |
 
-- **仅增删普通参会人/群组，不改时间，也不涉及会议室**：定位完成后可直接进入最终 `+update`。
-- **新增会议室，但不改时间**：必须基于已定位日程的当前 `start/end` 作为时间块执行 `+room-find`，不能因为用户没重复说时间就退回“无时间信息”。
-- **既改时间，又新增会议室**：必须先处理时间，拿到最终候选时间块后，再基于该时间执行 `+room-find`；最终只增量添加新会议室，不自动删除已有会议室。
-- **既改时间，又更换会议室**：必须先处理时间，拿到最终候选时间块后，再基于该时间执行 `+room-find`；只有在用户明确表达“更换”时，最终才执行“移除旧会议室 + 添加新会议室”。
-- **只改时间，不涉及会议室**：沿用下方时间工作流，但最终落地必须是 `+update`，不是 `+create`。
+## 新建日程：智能推断默认值
 
-### 2. 新建日程：智能推断默认值
-以下信息智能推断，减少频繁询问用户：
+- **标题**：根据上下文自动生成；如无法推断，默认"会议"
+- **参会人**：如未指定，默认仅用户自己
+- **时长**：基于上下文推断；默认 30 分钟
+- **无时间信息**：默认推断合理区间（如"今天"或"近两天"），进入时间推荐流程，禁止询问用户
 
-- **标题**：根据上下文自动生成，例如“沟通对齐”“需求讨论”；如无法推断，默认为“会议”
-- **参会人**：如未明确指定其他人，默认参会人仅为**用户自己**
-- **时长**：基于会议类型和上下文动态推断；如无法推断，默认为 30 分钟
-- **无任何时间信息**：默认推断一个合理区间（如“今天”或“近两天”），并进入时间推荐流程，禁止询问用户
+搜索参与人出现多个结果无法唯一确定时，必须询问用户并记录长期记忆。
 
-当搜索特定参与人（人、群）出现多个结果无法唯一确定时，必须询问用户进行选择确认，并将该偏好记录为长期记忆，以便后续自动识别。
-
-### 3. 判断时间是否明确
-
-这一步判断的是**最终要落地的目标时间**，不是只看用户原句里有没有重复说时间。
+## 判断时间是否明确
 
 时间基准规则：
+- **新建流**：使用用户给出的时间，或默认补全出的时间范围
+- **编辑流且不改时间**：已定位日程的当前 `start/end` 就是明确时间
+- **编辑流且改时间**：用户想改到的新时间；若表达模糊，进入模糊时间分支
+**注意**: 在执行修改日程/会议时间的任务时，必须先获取原日程的持续时长。如果用户只提供了新的开始时间，你必须根据原时长自动计算出新的结束时间，严格保持原时长不变，禁止擅自改变原日程的时长。
 
-- **新建流**：使用用户给出的时间，或默认补全出的时间范围作为时间基准。
-- **编辑流且不改时间**：已定位日程的当前 `start/end` 就是时间基准。后续如需查会议室，直接使用这个明确时间块。
-- **编辑流且改时间**：用户想改到的新时间才是时间基准；若表达模糊，则进入 `+suggestion`。
+## 分支路由
 
-分两类处理：
+| 判定结果 | 下一步读取 |
+|----------|-----------|
+| 明确时间 | [schedule-clear-time.md](./lark-calendar-schedule-clear-time.md) |
+| 模糊时间 / 无时间信息 | [schedule-fuzzy-time.md](./lark-calendar-schedule-fuzzy-time.md) |
 
-- **明确时间**：如“明天下午3点”
-- **模糊时间**：如“明天下午”“下周找个时间”
-
-### 4. 明确时间
-
-明确时间时，需先判断是否需要会议室，如果需要，提前查询会议室；然后判断是否有时间冲突。这里的“明确时间”既可以来自用户直接表达，也可以来自已定位日程的原始时间。
-详见 [`+room-find`](./lark-calendar-room-find.md) 与 [`+freebusy`](./lark-calendar-freebusy.md)。
-
-```bash
-# 1. 如果需要会议室，提前查询会议室
-lark-cli calendar +room-find \
-  --slot "<start>~<end>" \
-  --attendee-ids "<ids>" \
-  --city "<city>" \
-  --building "<building>" \
-  --floor "<F2>" \
-  --room-name "<room_name>"
-
-# 2. 查询当前用户及其他参会人忙闲
-# （如果有多名参会人，需分别调用查询：--user-id "<ou_xxx>"）
-lark-cli calendar +freebusy --start "<start>" --end "<end>"
-```
-
-规则：
-
-- **参会人过多或包含群组时的处理**：
-  - 如果参与人过多（例如超过 5 人），为避免高耗时，仅需查询**当前用户（自己）**及少数核心人员的忙闲状态即可。
-  - 如果参与人中包含**群组**，无需展开群组成员查询其忙闲状态。
-- **编辑已有日程且不改时间，只新增会议室时**：这里的 `--slot` 必须来自已定位日程的当前 `start/end`。
-- **编辑已有日程且既改时间又加会议室时**：这里的 `--slot` 必须来自候选新时间，而不是旧时间；如果用户是“新增会议室”，后续落地只做添加，不删除旧会议室。
-- **如果没有冲突**：直接让用户选择会议室（如需），然后进入最终落地操作：创建新日程，或更新既有日程
-- **如果有冲突**：必须先说明冲突情况，询问用户继续选择这个时间还是换个时间
-  - **如果说换个时间**：放弃当前时间，转入【模糊时间】流程，调用 `+suggestion` 推荐多个可用时间块
-  - **如果继续选择这个时间**：直接让用户选择会议室（如需），然后进入最终落地操作：创建新日程，或更新既有日程
-- 位置信息要优先拆到结构化字段：用户明确说了城市才提取 `--city`；`--building` 不要再重复携带城市前缀。
-- 参数归类顺序应为：`city/building/floor` > `floor + room-name` 复合表达 > `room-name`。像 `2L`、`2F` 这类更像楼层或区域定位的短词，优先视为 `--floor`，不要默认当作 `--room-name`。像 `学清2层` 这种表达，通常拆为 `--building "学清"` 与 `--floor "F2"`。
-- 会议室名要做轻量归一化：`木星会议室` -> `--room-name "木星"`；`会议室 02` / `02会议室` -> `--room-name "02"`。
-- 对 `F3-05` / `F5-07` / `3楼-08` 这类复合表达，若能稳定识别楼层与会议室号，应优先提取为 `--floor + --room-name`，不要把整段直接退化成 `--room-name`。
-
-### 5. 模糊时间或无时间信息
-
-先调用：
-详见 [`+suggestion`](./lark-calendar-suggestion.md)；若需要会议室，再结合 [`+room-find`](./lark-calendar-room-find.md)。
-
-```bash
-lark-cli calendar +suggestion \
-  --start "<range_start>" \
-  --end "<range_end>" \
-  --attendee-ids "<ids>" \
-  --duration-minutes <n> \
-  --event-rrule "<rrule>"
-```
-
-规则：
-
-- 若用户完全没有提供时间信息，应先默认一个合理区间后再调用 `+suggestion`
-- 编辑流中，若用户表达的是“改到明天下午”“下周找个时间再约”这类模糊新时间，则基于用户期望的新时间范围调用 `+suggestion`；不要继续沿用旧时间。
-- **不需要会议室**：获取多个推荐时间块后，直接向用户展示候选时间，用户确认后进入最终落地操作：创建新日程，或更新既有日程。
-- **需要会议室**：获取多个候选时间块后，**不要急于让用户选时间**。先将这些时间块一次性交给 `calendar +room-find` 批量查询可用会议室，然后将【候选时间】与【对应的可用会议室列表】结构化分行展示，让用户一次性完成选择。（**注意：即使用户最初只说“查会议室”，且未带时间，也必须强制走到这一步，先 suggestion 再 room-find**）。
-- 用户一旦选择了 `+suggestion` 返回的时间块，**无需再次调用 `+freebusy`**
-
-### 6. 模糊语义消解与长期记忆构建
-
-针对用户专属的时间表达习惯或存在歧义的时间场景，严禁主观臆断。典型例子包括：
-
-- “上班后”
-- “下班前”
-- 未明确上下午的 12 小时制时间表达
-
-处理规则：
-
-- 应主动澄清真实意图，而不是自行猜测
-- 当用户给出澄清后，应将这类个性化定义沉淀为长期偏好，推动后续直接理解类似表达
-
-### 7. 重复性日程
-
-若当前会议为重复性日程，调用 `+room-find` 时需携带 `--event-rrule`。
-
-必须检查返回中的：
-
-- `reserve_until_time`
-
-若候选会议室的可预约上限早于重复规则覆盖范围，**不要直接按原规则落地日程**。应：
-
-- 向用户明确说明该会议室最长可约至何时。
-- 若用户确认继续选用该会议室，你必须**自动将日程的重复规则结束时间缩短**至该 `reserve_until_time`，以防止会议室预约失败。
-
-### 8. 落地日程变更
+## 落地日程变更
 
 用户确认后调用：
-如果是新建会议，详见 [`+create`](./lark-calendar-create.md)。
-如果是更新既有日程，详见 [`+update`](./lark-calendar-update.md)。必须先定位目标 `event_id`，再按用户意图用 `+update` 独立执行字段更新、添加参会人/会议室、移除参会人/会议室，或组合这些动作。若用户意图是“新增会议室”，默认仅追加 `room_id`，不移除已有会议室。
+- 新建 → [`+create`](./lark-calendar-create.md)
+- 编辑 → [`+update`](./lark-calendar-update.md)
 
 ```bash
 lark-cli calendar +create \
@@ -214,52 +103,20 @@ lark-cli calendar +update \
   --start "<start>" \
   --end "<end>" \
   --add-attendee-ids "omm_new_room"
-
-# 仅当用户明确要求“更换会议室”时，才同时移除旧会议室并添加新会议室
-lark-cli calendar +update \
-  --event-id "<event_id>" \
-  --remove-attendee-ids "omm_old_room" \
-  --add-attendee-ids "omm_new_room"
 ```
 
-规则：
-- 新建日程时，可使用 `+create`
-- 更新既有日程时，优先使用 `+update`。改时间/标题/描述、添加参会人/会议室、移除参会人/会议室可以分别独立执行；
-- 编辑流必须始终沿用前面定位得到的目标 `event_id`；禁止在最后一步重新按标题猜测一次目标日程。
-- 编辑流中如果只是新增群组或普通参会人，不涉及时间和会议室，可直接 `+update --add-attendee-ids ...`。
-- 编辑流中如果是“新增会议室但不改时间”，必须先基于目标日程原始时间查到可用会议室，再 `+update --add-attendee-ids "<room_id>"`；默认保留已有会议室。
-- 编辑流中如果是“既改时间又新增会议室”，顺序必须是：先确定最终时间，再查会议室，最后一次性 `+update` 时间与新增会议室；默认保留已有会议室。
-- 编辑流中如果是“既改时间又更换会议室”，顺序必须是：先确定最终时间，再查会议室，最后一次性 `+update` 时间、移除旧会议室并添加新会议室。
-- 需要会议室时，将选中的 `room_id` 写入最终落地请求的参与人列表
-- 展示会议室候选时，必须保留 CLI/API 返回的完整 `room_name` 原值；允许附加“推断说明”，但禁止用摘要名、楼层及会议室号、容量/视频标签重组后的名称替换原值
-
-## 用户展示建议
-
-当向用户展示多个时间块及对应的多个会议室时，**必须使用结构化清晰的格式排版**。**严禁将时间与会议室名称放在同一行展示**，必须分行并使用编号列表呈现可用会议室，严禁将所有信息揉成一团纯文本堆叠。
-
-**推荐展示格式参考：**
-
-```text
-## 2026-03-27 周五
-
-[选项 1] 14:00 - 15:00（参会人均空闲）
-  可用会议室：
-  1. 学清嘉创大厦B座-F2-02🎦(7人)
-  2. 学清嘉创大厦B座-F2-05🎦(10人)
-
-[选项 2] 16:00 - 17:00（参会人均空闲）
-  可用会议室：
-  1. 学清嘉创大厦B座-F3-01🎦(6人)
-  2. 学清嘉创大厦B座-F3-06🎦(8人)
-
-💡 请回复您倾向的选项编号以及对应的会议室序号，我来为您完成预定。
-```
+落地规则：
+- 编辑流必须始终沿用前面定位得到的目标 `event_id`；禁止在最后一步重新猜测目标日程
+- 编辑流中"新增会议室"默认仅追加 `room_id`，不移除已有会议室
+- 仅当用户明确说"更换会议室"时，才同时 `--remove-attendee-ids` 旧 + `--add-attendee-ids` 新
+- 需要会议室时，将选中的 `room_id` 写入参与人列表
 
 ## 参考
 
+- [lark-calendar-schedule-clear-time.md](./lark-calendar-schedule-clear-time.md)
+- [lark-calendar-schedule-fuzzy-time.md](./lark-calendar-schedule-fuzzy-time.md)
 - [lark-calendar-room-find.md](./lark-calendar-room-find.md)
-- [lark-calendar-freebusy.md](./lark-calendar-freebusy.md)
 - [lark-calendar-suggestion.md](./lark-calendar-suggestion.md)
 - [lark-calendar-create.md](./lark-calendar-create.md)
-- [lark-shared](../../lark-shared/SKILL.md)
-- [lark-calendar](../SKILL.md)
+- [lark-calendar-update.md](./lark-calendar-update.md)
+- [SKILL.md](../SKILL.md)

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

@@ -1,29 +0,0 @@
-
-# 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-suggestion.md

@@ -1,6 +1,5 @@
 # calendar +suggestion
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。
 
 根据非明确时间或一段时间范围，推荐多个可用时间块方案。帮助用户解决协调时间的难题。
 
@@ -8,8 +7,6 @@
 - ✅ **当用户需求涉及寻找时间块，且时间未完全确定**（如`今天`、`近三天`、`本周`、`下午`, `无时间描述`）时，调用此工具来获取推荐时间块给用户选择（包括但不限于预约日程）。
 - ❌ **当用户已经明确了具体的时间点**（如`今天下午3点`），则**不需要**调用此工具
 
-需要的scopes: ["calendar:calendar.free_busy:read"]
-
 ## 命令
 
 ```bash
@@ -121,5 +118,4 @@ lark-cli calendar +suggestion \
 ## 参考
 
 - [lark-calendar-create](lark-calendar-create.md) — 创建日程
-- [lark-calendar-freebusy](lark-calendar-freebusy.md) — 查询忙闲时段和rsvp状态
-- [lark-calendar](../SKILL.md) — 日历完整 API
+- [lark-calendar](../SKILL.md) — skill 入口与路由

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

@@ -1,13 +1,10 @@
 # calendar +update
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 更新既有日程字段，或独立增量添加/移除参会人和会议室。
 
 `+update` 支持三类互相独立的动作：更新日程字段、添加参会人/会议室、移除参会人/会议室。它们可以单独执行，也可以在同一次命令中组合执行。
 
-需要的 scopes: ["calendar:calendar.event:update"]
-
 ## 推荐命令
 
 ```bash
@@ -43,7 +40,7 @@ lark-cli calendar +update \
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--event-id <id>` | 是 | 要更新的日程 ID。重复性日程要先定位到目标实例的 `event_id`，不要直接使用原重复日程 ID |
+| `--event-id <id>` | 是 | 要更新的日程 ID。重复性日程请根据操作范围选择 ID，详见 [重复性日程操作规范](lark-calendar-recurring.md) |
 | `--calendar-id <id>` | 否 | 日历 ID（省略则使用 `primary`） |
 | `--summary <text>` | 否 | 新日程标题。仅在显式传入 `--summary` 时更新；若传空字符串，会把标题清空 |
 | `--description <text>` | 否 | 新日程描述。目前 API 方式不支持编辑富文本描述；如果日程描述通过客户端编辑为富文本内容，则使用 API 更新描述会导致富文本格式丢失。仅在显式传入 `--description` 时更新；若传空字符串，会把描述清空 |
@@ -65,17 +62,15 @@ lark-cli calendar +update \
 - 只想修改标题、描述、时间或重复规则时，不需要同时传 `--add-attendee-ids` 或 `--remove-attendee-ids`。
 - 如需替换某个参与人、群组或会议室，使用 `--remove-attendee-ids <旧ID>` + `--add-attendee-ids <新ID>`。
 - 会议室是 resource attendee，必须使用 `omm_` ID 添加到参会人列表，不能脱离日程单独预定。
-- 更新重复性日程的某一次实例时，必须先通过 `+agenda`、`+search-event` 或实例视图定位该实例的 `event_id`。
-- 如果需要验证更新结果，等待至少 2 秒后再查询，避免同步延迟导致读到旧数据。
+- 更新重复性日程时，必须先确定操作范围（仅此次/全部/此次及后续），然后按 [重复性日程操作规范](lark-calendar-recurring.md) 执行。
 - 当同一次命令组合多个动作时，执行顺序为“日程字段 -> 移除参会人 -> 添加参会人”。若中途失败，不会自动回滚已成功步骤；错误信息会说明已完成的步骤。
+**⚠️ 高风险操作**: 修改时间时必须先读取原日程时长并计算新 end。如果 end 计算错误，会导致日程时长变化，用户会直接感知，禁止擅自改变原日程的时长。
 
 ## 高级用法（完整 API 命令）
 
 `+update` 只覆盖标题、描述、时间、重复规则，以及参会人/会议室的增量添加或移除。
 
-如需更新 `location`（地理位置，不含会议室位置）、`visibility`（日程公开范围）、自定义 `reminders`（提醒设置）、自定义 `attendee_ability`（参与人权限）、自定义 `free_busy_status`（日程忙闲状态）、`color`（颜色）、附件、视频会议信息、全天日程，或在新增参会人时配置可选参加状态 等高级参数，请改用完整的 API 命令。建议先通过 `lark-cli schema calendar.events.patch`、`lark-cli schema calendar.event.attendees.create`、`lark-cli schema calendar.event.attendees.batch_delete` 查看完整参数定义。
-
-> 完整 API 命令的时间参数是 **Unix 秒字符串**（非 ISO 8601）。
+如需更新 `location`（地理位置，不含会议室位置）、`visibility`、自定义提醒、参与人权限、忙闲状态、颜色、附件、视频会议信息、全天日程，或在新增参会人时配置可选参加状态，改用完整 API 命令并先通过 `lark-cli schema` 查看参数。完整 API 命令的时间参数是 **Unix 秒字符串**（非 ISO 8601）。
 
 ## 预约/改约会议室场景
 
@@ -98,8 +93,6 @@ lark-cli calendar +update \
 
 ## 参考
 
-- [lark-calendar](../SKILL.md) -- 日历全部命令
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
+- [lark-calendar](../SKILL.md) -- skill 入口与路由
 - [lark-calendar-schedule-meeting](lark-calendar-schedule-meeting.md) -- 预约/改约会议与会议室工作流
 - [lark-calendar-room-find](lark-calendar-room-find.md) -- 查找可用会议室
-- [lark-calendar-freebusy](lark-calendar-freebusy.md) -- 查询忙闲

skills/lark-doc/SKILL.md

@@ -5,7 +5,7 @@ description: "飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文
 metadata:
   requires:
     bins: ["lark-cli"]
-  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; lark-cli mindnotes nodes list --help; lark-cli mindnotes nodes create --help"
+  cliHelp: "lark-cli docs --help;lark-cli mindnotes --help"
 ---
 
 # docs
@@ -24,12 +24,12 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '<p>
 **CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：**
 1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用）
 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)
+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)
 
 **未读完以上文件就执行相应操作会导致参数选择错误或格式错误。**
 
 > **格式选择规则（全局）：**
-> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML（可用 callout、grid、checkbox 等富 block）。
+> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML。
 > - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。
 
 ## 快速决策
@@ -39,9 +39,10 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '<p>
 - 连续执行多个文档写操作时，必须按 [`lark-doc-update.md`](references/lark-doc-update.md) 的「Block ID 生命周期」判断旧 block ID 是否还能复用；`overwrite` / `block_replace` / `block_delete` 后不要复用受影响的旧 ID，插入 / 复制后要重新 fetch 才能拿到新 block ID
 - 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
 - 写文档时，由内容和用户意图决定表达形式；流程、架构、路线图、关键指标等信息可以使用画板，但不要默认把重要信息都画板化
-- 新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读 `lark-whiteboard`；复杂图才由主 Agent 先建 `<whiteboard type="blank"></whiteboard>`，再启动 SubAgent 读取 `lark-whiteboard` 写入
+- 新增或更新画板时，按 [`lark-doc-whiteboard.md`](references/lark-doc-whiteboard.md) 选型；Mermaid 可由主 Agent 直接插入，SVG / 复杂图 / 已有画板更新按其中流程隔离到 SubAgent
 - 用户说"看一下文档里的图片/附件/素材""预览素材" → 用 `lark-cli docs +media-preview`
 - 用户明确说"下载素材" → 用 `lark-cli docs +media-download`
+- 用户想把文档回滚到某个 `revision_id` 或某一时刻 → 先读 [`lark-doc-history.md`](references/lark-doc-history.md)，按其中流程操作
 - 用户明确说"下载/更新/删除文档封面图" → 用 `lark-cli docs +resource-download/+resource-update/+resource-delete --type cover`
 - `resource-*` 目前仅支持 Docx 封面资源；其他图片、附件或素材请走 `+media-*`
 - 如果目标是画板/whiteboard/画板缩略图 → 只能用 `lark-cli docs +media-download --type whiteboard`（不要用 `+media-preview`）
@@ -69,6 +70,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）
 | [`+create`](references/lark-doc-create.md) | Create a Lark document (XML / Markdown) |
 | [`+fetch`](references/lark-doc-fetch.md) | Fetch Lark document content (XML / Markdown / im-markdown; `im-markdown` only after fetch for `lark-im`) |
 | [`+update`](references/lark-doc-update.md) | Update a Lark document (str_replace / block_insert_after / block_replace / ...) |
+| [`+history-list` / `+history-revert` / `+history-revert-status`](references/lark-doc-history.md) | List document history, revert to a `history_version_id`, and query revert task status |
 | [`+media-insert`](references/lark-doc-media-insert.md) | Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback). Prefer `--from-clipboard` when the image is already on the system clipboard (screenshots, copy from Feishu/browser); use `--file` only for on-disk sources. |
 | [`+media-download`](references/lark-doc-media-download.md) | Download document media or whiteboard thumbnail (auto-detects extension) |
 | [`+media-preview`](references/lark-doc-media-preview.md) | Preview document media file (auto-detects extension) |

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

@@ -2,14 +2,14 @@
 
 > **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
 > 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
-> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
-> 3. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
+> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 写作原则（默认段落、按体裁、组件克制）
+> 3. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、单 Agent 串行撰写）
 >
 > **未读完以上文件就生成内容会导致格式错误。**
 
 从 XML（默认）或 Markdown 内容创建一个新的飞书云文档。
 
-> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，支持 callout、grid、checkbox 等富 block 类型）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。
+> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，可承载更丰富的结构化内容）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。
 
 ## 命令
 
@@ -72,8 +72,8 @@ lark-cli docs +create --doc-format markdown --title "项目计划" --content $'#
 
 ## 参考
 
-- [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
-- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档样式指南（元素选择 + 丰富度规则 + 颜色语义）
+- [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、单 Agent 串行撰写）
+- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档写作原则（默认段落、按体裁、组件克制）
 - [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
 - [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
 - [`lark-doc-update.md`](lark-doc-update.md) — 更新文档

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

@@ -0,0 +1,107 @@
+# docs history（历史版本与回滚）
+
+用于查看 Docx 历史版本、按 `history_version_id` 回滚，以及查询回滚任务状态。
+
+## 安全流程
+
+1. 先用分页接口 `+history-list` 找到目标版本的 `history_version_id`。
+2. 如果用户指定的是 `revision_id`，不要假设它唯一，也不要把 `revision_id` 直接传给 `+history-revert`。先拉一页并在 `entries[]` 中筛选 `revision_id` 相同的候选；如果未匹配到且 `has_more=true`，继续用 `page_token` 翻页；如果已匹配到候选，最多额外再拉一页补齐可能跨页的相邻候选。最终优先根据用户目标时间与 `edit_time` 的接近程度选择最合适的一条，取同一条的 `history_version_id`；如果没有目标时间，或多个候选无法可靠区分，再向用户展示候选版本（`history_version_id`、`revision_id`、`edit_time`、`name/description`）并确认后回滚。
+3. 如果用户指定的是某一时刻但没有指定 `revision_id`，按 `entries[].edit_time` 匹配；优先选择不晚于目标时刻的最近一条历史记录，无法明确匹配时先向用户确认候选版本。
+4. 再用 `+history-revert --history-version-id <history_version_id>` 发起回滚。默认最多等待 30 秒；如果返回 `status: running`，记录 `task_id`。
+5. 用 `+history-revert-status` 轮询 `task_id`，直到状态不再是 `running`。
+6. 回滚完成后，用 `docs +fetch` 读取文档确认内容。
+
+## 按 revision_id 或时间点回滚
+
+当用户说“回滚到 revision_id=42”“恢复到昨天下午 3 点的版本”这类需求时，流程是：
+
+1. 执行 `docs +history-list --doc <doc>` 获取第一页历史记录；`+history-list` 是分页接口，只有 `has_more=true` 且还需要更多候选时才继续传 `--page-token` 翻页。
+2. 如果用户给出 `revision_id`：先筛选当前页中 `entries[].revision_id == 用户给出的 revision_id`。如果未命中且 `has_more=true`，继续拉下一页；如果已经命中候选，最多额外再拉一页，补齐同一个 `revision_id` 可能跨页出现的相邻 `history_version_id`。若用户同时给出目标时间，在候选里选择 `edit_time` 与目标时间最接近的一条；若未给目标时间但候选只有一条，可直接使用；若多个候选无法可靠区分，不要自行取第一条，向用户展示候选并确认。
+3. 如果用户只给出时间：用 `entries[].edit_time` 匹配，选择目标时刻之前最近的一条；如果用户表达的是“最接近某时刻”，则选择绝对时间差最小的一条。
+4. 从最终匹配条目读取 `history_version_id`。`history_version_id` 对应服务端 `minor_history.version`，这是回滚接口需要的 ID。
+5. 执行 `docs +history-revert --doc <doc> --history-version-id <history_version_id>`。
+
+候选确认时使用类似格式：
+
+```text
+同一个 revision_id 命中多个历史版本，请确认要回滚哪一条：
+- history_version_id=11 revision_id=42 edit_time=2026-06-22T12:24:45Z name=...
+- history_version_id=12 revision_id=42 edit_time=2026-06-22T12:25:14Z name=...
+```
+
+## 命令
+
+```bash
+# 列出历史版本
+lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20
+
+# 翻页
+lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20 --page-token "<page_token>"
+
+# 回滚到指定 history_version_id（默认等待 30000ms）
+lark-cli docs +history-revert --doc "<docx_url_or_token>" --history-version-id 42
+
+# 只发起任务，不等待
+lark-cli docs +history-revert --doc "<docx_url_or_token>" --history-version-id 42 --wait-timeout-ms 0
+
+# 查询回滚任务状态
+lark-cli docs +history-revert-status --doc "<docx_url_or_token>" --task-id "<task_id>"
+```
+
+## 参数
+
+| 命令 | 参数 | 必填 | 说明 |
+|-|-|-|-|
+| `+history-list` | `--doc` | 是 | Docx URL/token，或可解析为 Docx 的 wiki URL |
+| `+history-list` | `--page-size` | 否 | 返回条数，范围 `1-20`，默认 `20` |
+| `+history-list` | `--page-token` | 否 | 上一页返回的 `page_token` |
+| `+history-revert` | `--doc` | 是 | Docx URL/token，或可解析为 Docx 的 wiki URL |
+| `+history-revert` | `--history-version-id` | 是 | `+history-list` 返回的 `history_version_id`，必须大于 0 |
+| `+history-revert` | `--wait-timeout-ms` | 否 | 等待回滚完成的毫秒数，范围 `0-30000`，默认 `30000` |
+| `+history-revert-status` | `--doc` | 是 | 同一个文档 |
+| `+history-revert-status` | `--task-id` | 是 | `+history-revert` 返回的 `task_id` |
+
+## 返回值要点
+
+`+history-list` 返回：
+
+```json
+{
+  "entries": [
+    {
+      "revision_id": 42,
+      "history_version_id": "11",
+      "edit_time": "1780000000",
+      "type": 1,
+      "name": "版本名",
+      "description": "版本说明",
+      "editor_ids": ["ou_xxx"]
+    }
+  ],
+  "has_more": true,
+  "page_token": "page_token"
+}
+```
+
+`+history-revert` 返回：
+
+```json
+{
+  "task_id": "task_xxx",
+  "status": "running",
+  "history_version_id": "11",
+  "poll_after_ms": 10000
+}
+```
+
+`+history-revert-status` 返回：
+
+```json
+{
+  "status": "partial_failed",
+  "history_version_id": "11",
+  "failed_block_tokens": ["blk_xxx"]
+}
+```
+
+`status` 可能是 `running`、`done`、`partial_failed`、`failed`。当状态是 `partial_failed` 或 `failed` 时，优先检查 `failed_block_tokens`。

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

@@ -3,8 +3,8 @@
 
 > **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
 > 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
-> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
-> 3. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）
+> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 写作原则（默认段落、按体裁、组件克制）
+> 3. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、单 Agent 串行改写）
 >
 > **未读完以上文件就生成内容会导致格式错误。**
 
@@ -232,7 +232,7 @@ lark-cli docs +update --doc "<doc_id>" --command str_replace \
 
 > **`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) 的「画板语法与插入」章节。
+画板的语法选型与插入示例见 [`lark-doc-xml.md`](lark-doc-xml.md) 与 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md)。
 
 ## 最佳实践
 
@@ -252,8 +252,8 @@ lark-cli docs +update --doc "<doc_id>" --command str_replace \
 
 ## 参考
 
-- [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）
-- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档样式指南（元素选择 + 丰富度规则 + 颜色语义）
+- [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、单 Agent 串行改写）
+- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档写作原则（默认段落、按体裁、组件克制）
 - [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
 - [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
 - [`lark-doc-create.md`](lark-doc-create.md) — 创建文档

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

@@ -13,6 +13,13 @@ lark-cli docs +fetch --doc "$URL" --doc-format xml --detail full --format json \
 
 `$URL` 可以是用户给出的 docx/wiki URL，也可以是可被 `docs +fetch` 解析的 token。
 
+## 统计范围
+
+先判断用户要求的是**整篇文档**还是**局部内容**：
+
+- 整篇文档的总字数 / 总字符数：按上方「调用方式」抓取 `full` 内容后统计。
+- 本次新增 / 替换 / 改写片段的字数：优先统计拟写内容本身；内容已写入文档时，只 fetch 对应 block / range 后统计。不得用整篇文档字数对比局部目标。
+
 如需在自动化或回归验证中发现未覆盖块类型，追加严格参数：
 
 ```bash
@@ -36,6 +43,15 @@ lark-cli docs +fetch --doc "$URL" --doc-format xml --detail full --format json \
 
 如果 `unknown_blocks` 或 `unsupported_blocks` 非空，回复用户时要说明“已统计可提取文本，但存在未覆盖块，结果可能偏低”，并列出对应块类型。为空时可直接给出结果。
 
+## 字数遵循校验
+
+当用户给了明确字数要求（写 N 字 / x-y 字 / x 字左右 / 上下浮动）时执行；没有明确字数要求则跳过。字数必须按本文流程用脚本统计，不要自己估。
+
+1. 先按「统计范围」确认统计对象，再把要求归一成目标区间：`>x`→`[x+1, +∞)`；`<y`→`(-∞, y-1]`；`x-y`→`[x, y]`；`x 字左右`→`[round(0.9x), round(1.1x)]`
+2. 按统计对象选择对应输入并调用脚本统计实际字数，读取输出里的 `word_count`
+3. 对比 `word_count` 与目标区间：区间内即通过；低于下限 → 补充**实质内容**（非注水）；高于上限 → 删减冗余内容。改完重新统计
+4. **最多 2 轮**。2 轮后仍不达标：停止，不得为达标而注水或删关键内容；如实汇报【目标区间 / 当前字数 / 差值与方向 / 已试 2 轮 / 未达原因】，**禁止谎称达标**
+
 ## 输出示例
 
 输入正文等价于：`标题` + `一个苹果是 an apple。` 时，输出形态如下：

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

@@ -7,7 +7,7 @@
 通过自适应的 **Code-Act Loop** 驱动文档创作，而非固定模板式的工作流。每次任务都循环执行：
 
 1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么
-2. **Execute（执行）** — 运行相应的 `lark-cli docs` 命令，或 **spawn** Agent 子任务并行推进
+2. **Execute（执行）** — 由主 Agent 自己运行 `lark-cli docs` 命令推进正文；仅画板渲染按需隔离到 SubAgent（见步骤三）
 3. **Observe（观察）** — 检查命令输出，验证正确性，确认内容是否满足用户目标
 4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
 
@@ -16,44 +16,32 @@
 
 ## 典型 Code-Act Loop 流程
 
-### 步骤一：规划与初始创建（串行）
+### 步骤一：规划与撰写（单 Agent 串行）
+
+正文由主 Agent 串行维护，**不按章节拆给并行 Agent**，避免上下文割裂、重复矛盾和全文级约束失效。
 
 1. 分析用户需求：受众、目的、范围
 2. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
-3. `docs +create` 创建文档。长文档可**只建骨架**：标题 + 各级标题 + 每节一句占位摘要；短文档可以一次写入完整内容
-   - ⚠️ 创建较长文档时，**不要**一次性把完整章节内容塞进 `--content`。超长 `--content` 容易触发字符/参数限制。
-   - 完整内容留到步骤二，由各 Agent 用 `block_insert_after --block-id <章节标题 block_id>` 分段写入。
-   - ⚠️ **`@file` 路径限制**：`--content @file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下，用完自行清理。
+3. `docs +create` 创建并撰写：
+   - **短文档**：一次写入完整内容。使用 Markdown 时，避免同时传入 `--title` 和同名 `# 标题`
+   - **长文档**：先建骨架（标题 + 各级标题），再由主 Agent **顺序逐节**用 `block_insert_after --block-id <章节标题 block_id>` 补全正文；写完一节再写下一节，始终带着已写内容的上下文，保证衔接、不重复
+   - ⚠️ 不要一次性把超长完整内容塞进 `--content`，容易触发字符/参数限制；长文按节分次写入
+   - ⚠️ 同一节内多次插入时，要锚到**上一个新插入的 block**（按 [`lark-doc-update.md`](../lark-doc-update.md) 的「Block ID 生命周期」），否则反复锚同一个标题会让段落顺序颠倒
+   - ⚠️ 若先建骨架写了占位摘要，补正文时**删除占位摘要**，不要留残渣
+   - ⚠️ **`@file` 路径限制**：`--content @file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下，用完自行清理
 
-### 步骤二：分段撰写（并行 Agent）
+### 步骤二：整合审查与画板识别（串行）
 
-4. Spawn Agent 并行撰写各章节。每个 Agent 需收到：
-   - 文档 token、负责的章节范围、用户目标、目标读者和已有风格线索
-   - `lark-doc-xml.md` 和 `lark-doc-style.md` 的完整路径（Agent 须先读取）
-   - 使用 `block_insert_after --block-id <章节标题 block_id>` 写入对应章节内容
+4. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果
+5. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材；检查跨节有无重复、矛盾或断流。再按 `lark-doc-style.md` 的「写完自检」快速核对，发现问题就地定向修正
+6. **画板识别**：逐章节扫描，判断是否有段落用图明显比文字更易懂（流程 / 架构 / 时间线 / 对比 / 占比等，见 `lark-doc-style.md` 的画板原则）。默认用文字，只有确需图示才记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
 
-### 步骤三：整合审查与画板识别（串行）
+### 步骤三：画板处理与润色
 
-5. `docs +fetch --detail with-ids` 获取文档，审查整体效果
-6. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材
-7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
+7. **优先处理步骤二识别出的画板需求**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent
+8. 由**主 Agent 自行润色**（不另起内容子 Agent，正文始终一人维护）：文字密集且不易读时，优先拆段、加小标题或调整顺序——叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`）；只有确实存在行列数据时才用 `<table>`。其余富 block 的取舍一律遵循 `lark-doc-style.md` 的写作原则，不主动堆叠。需要明显分隔的主题可补充 `<hr/>`，不强制章节间都使用。本地图片使用 `docs +media-insert` 插入
 
-### 步骤四：画板处理与润色（并行 Agent）
+### 步骤四：专项校验
 
-8. **优先处理步骤三识别出的画板需求**：
-   参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。
-9. Spawn 内容改写 Agent 定向润色：
-   - 文字密集且不易读时，优先拆段、改列表、增加小标题或调整顺序；只有确实存在行列数据、并列对比或强提醒信息时，才考虑 `<table>` / `<grid>` / `<callout>`
-   - 需要明显分隔的主题可补充 `<hr/>`，不强制章节间都使用
-   - 本地图片使用 `docs +media-insert` 插入
-
-
-## Agent 子任务要求
-
-内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、用户目标/风格要求、具体的 `docs +update` command 和 `--block-id`。
-
-Mermaid 图由主 Agent 直接插入 `<whiteboard type="mermaid">...</whiteboard>`，无需 SubAgent。
-
-SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径，以及[lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的 "SVG 设计 Workflow" 指南。它只负责插入一个 `<whiteboard type="svg">...</whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。
-
-已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。
+9. **字数门禁**：如果用户给出任何明确字数要求（如“700-800 字”“1000 字左右”“不少于 500 字”“控制在 800 字以内”），本步骤必须执行，不属于按需项。读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；未得到脚本统计结果前，不得向用户声明“符合字数要求”。若没有明确字数要求，则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现目标区间、`word_count` 和达标结论
+10. **重复标题检查**：文档生成后，检查文档标题和正文第一个标题块是否重复；若重复，删除或改写正文第一个标题块，避免读者看到同一标题连续出现

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

@@ -1,86 +1,68 @@
-# 文档表达组件参考
+# 飞书文档写作原则
 
-本文件说明飞书文档可用的结构化表达方式，供模型在需要时选择。它不是固定模板，也不是强制排版规范。
+写飞书文档，像一个该领域资深的人类作者那样写，而不是把内容"装配"成组件。
+本文只讲"何时用、什么风格"；具体标签 / 命令语法见 [`lark-doc-xml.md`](../lark-doc-xml.md)。
 
-默认原则：优先理解用户目标、受众、素材形态和已有文档风格，由模型自主决定结构、语气和视觉呈现。只有当用户明确要求“美化、重排版、做成报告/方案/看起来更专业”等，或内容本身明显需要结构化承载时，才主动使用下列组件。
+## 一、用户明确要求优先
 
-## 一、核心原则
+用户点名要某种格式——高亮块、分栏、列表、某编号体例、表格、画板、某模板、某已有文档的风格——**一律照用户的来，下面的"默认克制"全部让位**。用户给了样例或已有文档，就沿用它的结构与语气。
 
-1. **服务内容，而非套模板**：先判断信息最自然的表达方式，再选择段落、列表、表格、分栏、画板等元素
-2. **尊重用户风格**：用户给出样例、语气、结构或已有文档时，优先沿用；没有要求时不强行使用固定开头、固定章节或固定视觉组件
-3. **适度结构化**：结构化 block 用于降低理解成本，不为了“丰富”而堆叠
-4. **保持一致但不过度统一**：同类信息可使用相近表达，但允许因内容差异采用不同形式
-5. **图示服务理解**：流程、架构、对比、风险、路线图、指标趋势等内容在图示明显降低理解成本时，可使用画板表达
+## 二、默认写连贯段落
 
-## 二、元素选择指南
+用户没指定时，**默认是连贯段落**；其余按内容类型分流，别一律"少用结构"，也别什么都升标题：
 
-需要图表时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图可用 `<whiteboard type="mermaid">` 直接内嵌；其他新图表可启动 SubAgent 插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；只有编辑**已有**画板时才调用 **lark-whiteboard** skill。
+| 内容 | 用什么 | ❌ 别 |
+|---|---|---|
+| 叙述、论证、分析、说明 | **连贯段落** | 拆成列举 |
+| 真·行列数据（预算、指标、对比、排期、字段说明） | **表格** | 写成段落或把字段堆成一行 |
+| 字段:值（主题、时长、负责人等，少量） | **加粗标签行**或一句话 | 每字段一个标题 |
+| 方法 / 措施 + 每项一段描述 | **加粗引导句段落**（「**全程督导。**…」） | 每项升标题 |
+| 任务清单 / 检查项 / 待办事项 | **`<checkbox>`** | 用普通列表替代可交互待办 |
+| 纯短并列项（无描述，如材料清单） | 列表 | — |
+| 章节（内容成块、需在目录导航） | 标题层级 | — |
 
-| 场景                                         | 可选表达方式                                |
-|--------------------------------------------|---------------------------------------|
-| 少数需要视觉提醒的短句，如风险、限制、待确认事项或关键提醒          | 需要视觉提醒时可用 `<callout>`；普通结论、摘要或章节导语优先使用段落、列表、小标题或加粗 |
-| 方案对比 / 优劣势 / Before vs After                | 简短对比可用段落、列表或 `<grid>`；维度较多且需要逐项比较时再考虑 `<table>` 或画板 |
-| 简短低风险对比                                    | `<grid>` 2 列分栏                        |
-| 需要按行列精确比较或查阅的数据，如指标、清单、字段说明、排期           | 可用 `<table>`；短要点、步骤、摘要或普通说明优先使用段落、列表或小标题 |
-| 任务清单 / 检查项                                 | `<checkbox>`                          |
-| 代码片段                                       | `<pre lang="x" caption="说明">`         |
-| 引用 / 公式                                    | `<blockquote>` / `<latex>`            |
-| 操作入口 / 跳转链接                                | `<button>` / `<a type="url-preview">` |
-| 流程图 / 时间线 / 示意图 / 自定义图形 / 架构图 / 数据图 / 思维导图等 | 画板图表                                  |
+- 判断标准：**去掉结构后能顺成段落，就用段落；成行成列的数据，就用表格。**
+- **红线一：标题层级只给"章节"。** "小标题 + 一两句话"的小项（字段、方法、要点）不该占标题层级——按上表降成标签行 / 加粗引导句段落（否则目录里全是没信息量的条目）。
+- **红线二：列举（「一是 / 二是」「第一 / 第二」「(1)(2)(3)」）只给真正并列的具体项，且别每节都用。**
+  - 「一是 / 二是」是党务列举的措辞——只用在列具体的**问题 / 措施**那一处；背景、现状、认识、分析、过渡、总结**一律成段**。
+  - **整篇每段 / 每节都"一是 / 二是"，和"每段一个 bullet"是同一个骨架化的错——不因为是党务就变对**（纯清单 / 台账类除外）。
 
+## 三、按体裁写
 
-### 画板意图识别
+- **公文 / 法律 / 学术 / 申报 / 项目方案等严肃正式提交物**：靠规范的标题层级、段落与编号体系表达；**默认不用高亮块、分栏**，要强调用加粗或规范小标题。
+- **面向公众号、微信等外部平台粘贴 / 发布的内容**：不用飞书特有富 block（高亮块、分栏等），粘出去会丢样式 / 错乱；改用标准标题、段落、列表、引用。
+- **一般文档**：以可读为先，不堆砌结构。
 
-撰写或审查每个段落/章节时，**必须判断该内容是否适合用图表达**。满足以下任一特征时，应使用画板而非纯文本；如果该内容承载章节核心结论、关键决策或主要论据，即使结构较简单也优先画板化：
+## 四、编号与层级
 
-| 内容特征 | 信号词 / 模式 | 推荐画板类型 |
+- **一套编号体例、全篇一致；最忌中文大层级与阿拉伯小数编号混用。**
+  - 公文 / 正式材料常用：「一、→（一）→ 1.→（1）」（中文大层级 + 阿拉伯细分层级）。
+  - 学术 / 技术 / 商业报告：「1 → 1.1 → 1.1.1」或「一、→（一）→ 1.」，**择一**。
+  - ⚠️ **「一、」只能配「（一）」；要用阿拉伯小数就从顶层全用「1 / 1.1」。绝不「一、」配「1.1 / 2.1」**——这是最常见的混用。
+  - **不混用**多套（别"第X部分"+"一、"+"1."混着来）；**同级不跳号**；**不跳级**。
+- **编号 / 标题层级只给"章节"**，不要为了凑齐体例把每个小项都编上「（一）」、升成标题（小项处理方式见上文「二、默认写连贯段落」）。
+- 简单的 1.2.3 并列项用原生 `<ol><li seq="auto">…</li></ol>` 让飞书自动编号、自动对齐；「一、(一)」原生产不出，才手打成文字——此时用标题级别表达层次，**不靠手动缩进**、各级顶格（全角括号「（）」叠手动缩进会视觉错位）。
+
+## 五、飞书特有组件，克制使用
+
+- **高亮块 `<callout>`**：很重的强提醒信号，**默认不用**；只给"不提醒就会出错 / 遗漏"的关键项，全文极少（0~1 个），不要每节导语 / 结论都做成高亮块。
+- **分栏 `<grid>`**：仅左右信息量相当、确需并排对照的短内容；否则用段落或表格。
+- **画板**：默认用文字，只在**图示明显比文字更易懂**（流程、架构、时间线、对比、占比等）或用户要求时才用。怎么插、用哪种类型见 [`lark-doc-xml.md`](../lark-doc-xml.md) 与 [`lark-doc-whiteboard.md`](../lark-doc-whiteboard.md)。
+- **颜色**：默认朴素、不上色；需要时保持语义一致，按下表选择对应颜色，不为装饰上色。可用色见 [`lark-doc-xml.md`](../lark-doc-xml.md) 的「美化系统」。
+
+| 语义 | 背景色 | 文字色 |
 |-|-|-|
-| 多步骤的操作流程或决策路径 | "先…然后…最后"、"步骤 1/2/3"、"如果…则…否则" | 流程图 / 泳道图 |
-| 系统或模块间的依赖与交互 | "调用"、"依赖"、"上游/下游"、"请求→响应" | 架构图 |
-| 上下级或从属关系 | "汇报给"、"下属"、"隶属"、"团队结构" | 组织架构图 |
-| 时间线或阶段演进 | "Q1/Q2"、"里程碑"、"阶段一→阶段二"、日期序列 | 时间线 / 里程碑 |
-| 因果分析或问题归因 | "根因"、"原因"、"导致"、"影响因素" | 鱼骨图 |
-| 两个及以上方案/对象的多维度对比 | "vs"、"方案 A/B"、"优劣"、"对比" | 对比图 |
-| 层级递进或优先级排序 | "基础→进阶→高级"、"L1/L2/L3"、"核心→外围" | 金字塔图 |
-| 数值趋势或周期变化 | 带数字的时间序列、"增长/下降"、百分比变化 | 折线图 / 柱状图 |
-| 漏斗或转化率 | "转化率"、"漏斗"、"从…到…留存" | 漏斗图 |
-| 发散或归纳的思维结构 | "要点"、"维度"、"分支"、多层嵌套列表 | 思维导图 |
-| 循环或飞轮效应 | "正循环"、"飞轮"、"闭环"、"A 驱动 B 驱动 C" | 飞轮图 |
-| 占比分布 | "占比"、"份额"、"分布"、百分比加总 ≈100% | 饼图 / 树状图 |
+| 信息、说明 | `light-blue` | `blue` |
+| 成功、推荐 | `light-green` | `green` |
+| 警告 / 错误 / 风险 | `light-red` | `red` |
+| 注意、待确认 | `light-yellow` | `yellow` |
+| 中性、辅助 | `light-gray` | — |
 
-**判断规则：**
-- 重要信息能图示就图示；不要为了省步骤把关键流程、架构、对比、风险链路写成纯文本
-- 低重要度、局部辅助信息才用 `<table>` / `<grid>` / `<callout>` 承载
-- 确定需要插入哪些图表后，参照 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的方式，插入图表画板。
+## 六、写完自检
 
-## 三、颜色语义
-
-如果使用颜色，建议保持语义一致；不需要颜色时可以保持朴素文本风格：
-
-| 语义 | emoji 前缀 | callout 背景色 | 文字色 |
-|-|-|-|-|
-| 信息、说明 | ℹ️ "说明：" | `light-blue` | `blue` |
-| 成功、推荐 | ✅ "推荐：" | `light-green` | `green` |
-| 警告 / 错误 / 风险 | ⚠️❌ | `light-red` | `red` |
-| 注意、待确认 | ❗"注意：" | `light-yellow` | `yellow` |
-| 中性、辅助 | — | `light-gray` | — |
-
-- 表头可使用 `background-color="light-gray"`，也可以保持默认样式
-- 关键指标如使用 `<span text-color="green/red">` 突出，建议同时用 ↑↓ 或 +/- 标注方向（色觉无障碍）
-
-## 四、排版规范
-
-- 标题层级、段落长度、列表嵌套和 Grid 列数应以可读性为准，避免过深层级和过宽分栏
-- 文档开头可以是结论、背景、摘要、问题陈述、目录或直接正文，不强制使用 `<callout>`
-
-## 五、质量自检
-
-生成内容后可以从以下角度自检，但不要把这些项当作硬性比例或固定模板：
-
-| 指标 | 自检问题 |
-|-|-|
-| 信息表达 | 当前结构是否符合用户目标，而不是套用固定报告模板？ |
-| 阅读负担 | 是否有段落过长、层级过深、表格过宽或组件过多的问题？ |
-| 风格匹配 | 是否延续了用户给定样例或已有文档风格？ |
-| 组件必要性 | callout、grid、table、whiteboard 等是否真的提升理解？ |
-| 保真度 | 改写时是否保留了原文事实、引用、图片、附件和资源块？ |
+交付前快速回看：
+- **叙述是否被列举化**：背景 / 现状 / 认识 / 分析 / 成效 / 过渡 / 总结等应成段；列举只用于同层级、可并列处理的信息，如问题、措施、步骤、任务或材料清单。若正文反复使用连续编号、项目符号或固定并列句式，导致内容缺少叙述，应把背景 / 认识 / 分析 / 过渡改写成有承接关系的段落（纯清单 / 台账类除外）。
+- **数据是否正确呈现**：成行成列的数据应使用表格呈现，不要写成段落，也不要用分隔符把多个字段硬串在一起。
+- **标题是否滥用**："小标题 + 一句话"的小项不要升成标题；应改成标签行、加粗引导句段落或普通段落。
+- **编号是否统一**：全篇一套、不跳号、不跳级，尤其不要中文 + 阿拉伯混用（如「一、」配「1.1」）。
+- **组件是否克制且保真**：高亮块 / 分栏 / 画板 / 颜色应符合体裁和用户要求；引用 / 图片 / 资源块必须保留。

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

@@ -5,7 +5,7 @@
 ## 核心方法论 — Code-Act Loop
 通过自适应的 **Code-Act Loop** 驱动文档改写，而非固定模板式的工作流。每次任务都循环执行：
 1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么
-2. **Execute（执行）** — 运行相应的 `lark-cli docs` 命令，或 **spawn** Agent 子任务并行推进
+2. **Execute（执行）** — 由主 Agent 自己运行 `lark-cli docs` 命令推进改写；仅画板渲染按需隔离到 SubAgent（见步骤二）
 3. **Observe（观察）** — 检查命令输出，验证正确性，确认内容是否满足用户目标
 4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
 
@@ -23,33 +23,26 @@
    - 需要精确跨节区间 → `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"
+   - 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) 中「选 `--scope`（读取范围）」小节
 2. 系统性评估：用户想改什么、现有文档风格是什么、哪些内容需要保留、哪些问题影响理解
-3. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断哪些段落的信息适合用图表达。重要信息优先画板化，记录需要插图的章节（block ID）、推荐画板类型、mermaid/SVG路径和源内容片段
+3. **画板识别**：逐章节扫描，判断是否有段落用图明显比文字更易懂（流程 / 架构 / 时间线 / 对比 / 占比等，见 `lark-doc-style.md` 的画板原则）。默认用文字，只有确需图示才记录需要插图的章节（block ID）、推荐画板类型、mermaid/SVG路径和源内容片段
 4. 向用户简要说明改进计划（包含识别出的画板机会）
 
-### 步骤二：定向改写（并行 Agent）
+### 步骤二：定向改写（单 Agent 串行）
 
-5. **优先处理步骤一识别出的画板候选段落**：
-   参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。
-6. Spawn 内容改写 Agent 在不重叠的章节上并行改进，各 Agent 收到文档 token 和特定 block ID：
+5. **优先处理步骤一识别出的画板候选段落**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent
+6. 由主 Agent **顺序逐节**改写，**不按章节拆给并行 Agent**，避免上下文割裂、重复矛盾和全文级约束失效：
    - 沿用或轻微调整已有文档风格，除非用户要求彻底重排版
-   - 优先通过重写段落、调整标题、拆分列表或补充小标题提升可读性
-   - 富 block 是可选表达手段，不因固定比例而添加；画板类需求只走第 5 步
+   - 优先通过重写段落、调整标题、补充小标题提升可读性；叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`）
+   - 富 block 是可选表达手段，不因固定比例而添加，取舍遵循 `lark-doc-style.md` 的写作原则；画板类需求只走第 5 步
 
 ### 步骤三：验证（串行）
 
 7. 获取更新后文档局部内容，检查是否符合用户目标和已有风格
-8. 检查是否满足用户目标并保留原有关键内容；如仍有明显问题则定向修正，向用户呈现结果
+8. 检查是否满足用户目标并保留原有关键内容。再按 `lark-doc-style.md` 的「写完自检」快速核对，发现问题则定向修正
 
-## Agent 子任务要求
+### 步骤四：专项校验（按需执行）
 
-内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、用户目标/风格要求、具体的 `docs +update` command 和 `--block-id`。
+9. 仅当用户预期需要校验字数时，才读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；否则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现结果
 
-Mermaid 图由主 Agent 直接插入 `<whiteboard type="mermaid">...</whiteboard>`，无需 SubAgent。
-
-SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径，以及[lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的 "SVG 设计 Workflow" 指南。它只负责插入一个 `<whiteboard type="svg">...</whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。
-
-已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。
-
-**上下文节省提示**：Agent 如需在自己负责的章节内重新读取内容，优先用 `docs +fetch --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

@@ -29,6 +29,7 @@ metadata:
 - 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
 - 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
 - 用户要把本地 `.pptx` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX 导入上限是 500MB。
+- 批量执行 `drive +import` 且目标是同一个位置（同一 `--folder-token`、默认根目录，或同一 `--target-token`）时，必须串行执行；不要并发导入到同一位置，服务端可能返回并发冲突错误。
 - 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../lark-markdown/SKILL.md)。
 - 用户要比较原生 `.md` 文件的**历史版本差异**，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。
 - 用户要查看、下载、回滚或删除文件的**历史版本**，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；这组命令同时支持 `--as user` 和 `--as bot`，自动化场景优先 `--as bot`。
@@ -102,6 +103,7 @@ lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
 | `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
 | `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
 | `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides/bitable） |
+| `232140101` / `232140100` / `233523001`（常见于 `drive +import` 的 `job_error_msg`） | 同一位置下存在并发导入 / 创建操作 | 批量导入到同一文件夹、根目录或同一 `--target-token` 时改为串行执行；每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突 |
 
 ### 权限能力入口
 

skills/lark-drive/references/lark-drive-import.md

@@ -14,6 +14,13 @@
 > [!IMPORTANT]
 > 当用户**未传 `--name`** 时，文档标题默认取源文件名（去掉扩展名）。在执行导入前，先友好提示用户：「当前未指定文档标题，默认将使用"xxx"作为标题。如果文件内容中也包含相同标题，导入后可能造成视觉重复。是否需要重命名？」让用户确认后再继续。
 
+## 批量导入串行规则
+
+> [!IMPORTANT]
+> 批量执行 `drive +import` 且目标是同一个位置时，必须串行执行，不要并发发起导入任务。这里的“相同位置”包括同一个 `--folder-token`、都省略 `--folder-token` 导入到默认根目录，或使用同一个 `--target-token` 导入到已有 bitable。
+>
+> 如果在同一位置下并发导入，服务端可能返回并发冲突错误。看到错误信息或 `job_error_msg` 中包含 `232140101`、`232140100`、`233523001` 任一错误码时，按同位置并发操作处理：停止并发导入，改为串行处理失败项；每个失败项每次重试前等待几秒，总共最多重试 3 次；仍失败就停止并向用户报告冲突。
+
 ## 命令
 
 ```bash
@@ -143,6 +150,7 @@ lark-cli drive +import --file ./README.md --type docx --dry-run
 - “超过 20MB 自动切换分片上传”只表示上传链路会切到 multipart，不代表所有格式都允许导入超过 20MB 的文件。
 
 - 若导入任务执行失败，会返回失败时的 `job_status` 及错误信息。
+- 若导入失败信息包含 `232140101`、`232140100`、`233523001`，通常表示同一位置下存在并发导入 / 创建操作；批量场景请改为串行执行，每个失败项每次重试前等待几秒，总共最多重试 3 次，仍失败就停止并报告冲突。
 - 若内置轮询超时但任务仍在处理中，shortcut 会成功返回，并带上：
   - `ready=false`
   - `timed_out=true`

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

@@ -1,7 +1,6 @@
 
 # minutes +download
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 下载妙记的音视频媒体文件到本地，或获取有效期 1 天的下载链接。只读操作。
 
@@ -134,4 +133,3 @@ API 限流 5 次/秒，批量下载时需注意控制频率。
 
 - [lark-minutes](../SKILL.md) — 妙记全部命令
 - [lark-minutes-detail](lark-minutes-detail.md) — 妙记详情与 AI 产物查询
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -1,6 +1,5 @@
 # minutes +search
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 搜索妙记列表，支持关键词、所有者、参与者以及时间范围等多条件过滤。所有者与参与者都支持传入多个 open\_id，也支持传入 `me` 表示当前用户。只读操作，不修改任何妙记数据。
 
@@ -199,6 +198,5 @@ lark-cli minutes +detail --minute-tokens <minute_token> --summary
 
 - [lark-minutes](../SKILL.md) -- 妙记相关命令
 - [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

@@ -1,6 +1,5 @@
 # minutes +speaker-replace
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 替换妙记逐字稿中的说话人身份：把妙记逐字稿里"原说话人"对应的所有发言段，重新归属到"新说话人"。常用于解决妙记自动识别错说话人，或需要把外部/非飞书说话人改绑到正确飞书用户的场景。
 
@@ -106,4 +105,3 @@ Agent 必须先 `lark-cli api GET .../speakerlist`，再 `+speaker-replace`；`-
 ## 参考
 
 - [lark-minutes](../SKILL.md) -- 妙记相关功能说明
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -1,6 +1,5 @@
 # minutes +summary
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 替换妙记的 AI 总结内容。写操作，会覆盖当前总结。
 
@@ -119,4 +118,3 @@ lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @sum
 - [lark-minutes](../SKILL.md) — 妙记全部命令
 - [minutes +todo](lark-minutes-todo.md) — 替换待办项
 - [minutes +detail](lark-minutes-detail.md) — 读取总结、待办等 AI 产物
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -2,7 +2,6 @@
 
 > **路由**：本命令操作**妙记内的 AI 待办**，不是飞书任务（Task）。用户说「在妙记里新建待办」时**必须**用本命令，**禁止**走 `lark-cli task` / `tasklists list` / `task +create`。详见 [lark-minutes/SKILL.md](../SKILL.md) 第 6 节。
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 对妙记中的待办做新增 / 更新 / 删除（单条或批量）。写操作。
 
@@ -135,4 +134,3 @@ lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add -
 - [lark-minutes](../SKILL.md)
 - [minutes +summary](lark-minutes-summary.md)
 - [minutes +detail](lark-minutes-detail.md)
-- [lark-shared](../../lark-shared/SKILL.md)

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

@@ -1,6 +1,5 @@
 # minutes +update
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 修改飞书妙记的标题（topic）。
 
@@ -38,4 +37,3 @@ lark-cli minutes +update --minute-token xxx --topic "周会纪要 2026-05-18"
 ## 参考
 
 - [lark-minutes](../SKILL.md) -- 妙记相关功能说明
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

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

@@ -1,6 +1,5 @@
 # minutes +upload
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 上传音视频文件到飞书妙记并生成妙记（Minute）。
 
@@ -31,12 +30,12 @@
      ```
    - 命令执行成功后，将返回生成的妙记链接 `minute_url`。
 
-3. **如需纪要 / 逐字稿 / 文字稿 / 撰写文字，继续提取 `minute_token` 调用 `minutes +detail`**
-   - 从返回的 `minute_url` 中提取路径最后一段，得到 `minute_token`。
-   - 如果用户要的是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，继续调用：
+3. **如需纪要 / 逐字稿 / 文字稿 / 撰写文字，使用返回的 `minute_token` 调用 `minutes +detail`**
+   - 如果用户要的是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，使用上一步返回的 `minute_token` 继续调用：
      ```bash
-     lark-cli minutes +detail --minute-tokens <minute_token> --summary --todo --chapter --keyword --transcript
+     lark-cli minutes +detail --minute-tokens <minute_token> --wait-ready --summary --todo --chapter --keyword --transcript
      ```
+   - `--wait-ready` 参数表示等待妙记生成完毕后再获取产物，上传后立即读取详情时必须加上此参数。
    - `minutes +detail --minute-tokens` 会返回妙记产物（总结、待办、章节、关键词、逐字稿）；必要时还会把逐字稿落地到本地文件。
 
 > **异步生成提示**：API 会立即返回 `minute_url`，但妙记可能仍在异步生成中，您可以直接通过该妙记链接查看当前的处理状态和转写结果。
@@ -47,8 +46,8 @@
 # 通过已上传到云空间（云盘/云存储）的 file_token 生成妙记
 lark-cli minutes +upload --file-token boxcnxxxxxxxxxxxxxxxx
 
-# 通过 minute_token 继续获取妙记产物（--summary --todo --chapter --keyword --transcript 按需传入）
-lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --summary
+# 上传后立即获取妙记产物，需加 --wait-ready 等待生成完毕（--summary --todo --chapter --keyword --transcript 按需传入）
+lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --wait-ready --summary
 ```
 
 ## 参数
@@ -81,7 +80,7 @@ lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --summary
 1. 使用 `lark-cli drive +upload --file <path>` 上传本地音视频文件到云空间（云盘/云存储）
 2. 从返回结果中取出 `file_token`
 3. 调用 `lark-cli minutes +upload --file-token <file_token>` 生成妙记
-4. 如果目标是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，再从 `minute_url` 提取 `minute_token`，继续调用 `lark-cli minutes +detail --minute-tokens <minute_token>`
+4. 如果目标是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，使用返回的 `minute_token`，继续调用 `lark-cli minutes +detail --minute-tokens <minute_token> --wait-ready`
 
 > **边界说明**：`minutes +upload` 本身只负责把文件转成妙记并返回 `minute_url`。纪要内容、逐字稿、文字稿、撰写文字、总结、待办、章节属于后续产物获取，应由 [minutes +detail](lark-minutes-detail.md) 承接。
 
@@ -89,16 +88,17 @@ lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --summary
 
 ```json
 {
-  "minute_url": "http(s)://<host>/minutes/<minute-token>"
+  "minute_url": "http(s)://<host>/minutes/<minute-token>",
+  "minute_token": "<minute-token>"
 }
 ```
 
 | 字段 | 说明 |
 |------|------|
 | `minute_url` | 生成的妙记访问链接 |
+| `minute_token` | 从 `minute_url` 提取出的妙记 Token，可直接传给 `minutes +detail --minute-tokens` |
 
 ## 参考
 
 - [lark-minutes](../SKILL.md) -- 妙记相关功能说明
 - [drive +upload](../../lark-drive/references/lark-drive-upload.md) -- 上传文件到云空间（云盘/云存储）
-- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数

skills/lark-shared/SKILL.md

@@ -146,6 +146,24 @@ lark-cli update
 
 **重要**：始终使用 `lark-cli update` 更新，它会同时更新 CLI 和 AI Skills。
 
+## JSON 输出契约
+
+`--format json`（默认）下，成功与错误的信封结构不同：
+
+成功信封写入 **stdout**（退出码 0）：
+
+```json
+{ "ok": true, "identity": "user", "data": { "guid": "..." }, "meta": { "count": 1 } }
+```
+
+错误信封写入 **stderr**（退出码非 0）：
+
+```json
+{ "ok": false, "identity": "user", "error": { "type": "api", "subtype": "...", "code": 99991679, "message": "...", "hint": "..." } }
+```
+
+**判断成功必须用 `ok == true`（或进程退出码 0），不要用 `code == 0`**：成功信封没有顶层 `code` / `msg` 字段，`code` 只出现在错误信封的 `error` 内，含义是上游 OpenAPI 的 numeric code。按 OpenAPI 老格式 `{"code": 0, "msg": "ok"}` 判断会把所有成功调用误判为失败；封装写入类命令（如 `task +create`）时尤其危险，误判会绕过幂等逻辑导致重复创建。
+
 ## 安全规则
 
 - **禁止输出密钥**（appSecret、accessToken）到终端明文。

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

@@ -46,7 +46,20 @@ lark-cli task +create --summary "Test Task" --dry-run
 1. Confirm with the user: task summary, due date, assignee, and tasklist if necessary.
    - **Crucial Rule for Assignee**: If the user explicitly or implicitly says "create a task for me" (给我创建一个任务), or "help me create a task" (帮我新建/创建一个任务), you MUST assign the task to the current logged-in user. You can get the current user's `open_id` by executing `lark-cli auth status` (it already outputs JSON by default, so do not add `--json`) or `lark-cli contact +get-user` first, extracting `.identities.user.openId` (from `auth status`) or `.data.user.open_id` (from `contact +get-user`), and then passing it to the `--assignee` parameter.
 2. Execute `lark-cli task +create --summary "..." ...`
-3. Report the result: task ID and summary.
+3. Judge success by `ok == true` in the stdout JSON (the success envelope has no `code` field — do not test `code == 0`), then report the result: task ID (`data.guid`) and summary.
+
+Example success response:
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "guid": "e297d3d0-4b60-4a5f-a4d4-xxxxxxxxxxxx",
+    "url": "https://applink.larkoffice.com/client/todo/detail?guid=e297d3d0-4b60-4a5f-a4d4-xxxxxxxxxxxx"
+  }
+}
+```
 
 > [!CAUTION]
 > This is a **Write Operation** -- You must confirm the user's intent before executing.

skills/lark-vc/references/lark-vc-recording.md

@@ -1,7 +1,6 @@
 
 # vc +recording
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
 通过 meeting_id 或 calendar_event_id 查询对应的 minute_token。这是 VC 域和 Minutes 域之间的桥梁命令。只读操作。
 
@@ -151,4 +150,3 @@ lark-cli minutes +download --minute-tokens <minute_token>
 - [lark-vc](../SKILL.md) — 视频会议全部命令
 - [lark-vc-search](lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
 - [lark-minutes-detail](../../lark-minutes/references/lark-minutes-detail.md) — 获取会议纪要
-- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

tests/cli_e2e/calendar/calendar_get_dryrun_test.go

@@ -0,0 +1,66 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package calendar
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+func TestCalendar_GetDryRun(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
+	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
+	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"calendar", "+get",
+			"--calendar-id", "cal_dry",
+			"--event-id", "evt_dry",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	out := result.Stdout
+	require.Equal(t, "GET", gjson.Get(out, "api.0.method").String(), "stdout:\n%s", out)
+	require.Equal(t, "/open-apis/calendar/v4/calendars/cal_dry/events/evt_dry", gjson.Get(out, "api.0.url").String(), "stdout:\n%s", out)
+	require.Equal(t, "cal_dry", gjson.Get(out, "calendar_id").String(), "stdout:\n%s", out)
+	require.Equal(t, "evt_dry", gjson.Get(out, "event_id").String(), "stdout:\n%s", out)
+}
+
+func TestCalendar_GetDryRun_DefaultPrimary(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
+	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
+	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"calendar", "+get",
+			"--event-id", "evt_dry",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	out := result.Stdout
+	require.Equal(t, "<primary>", gjson.Get(out, "calendar_id").String(), "stdout:\n%s", out)
+}

tests/cli_e2e/docs/coverage.md

@@ -1,9 +1,9 @@
 # Docs CLI E2E Coverage
 
 ## Metrics
-- Denominator: 8 leaf commands
-- Covered: 3
-- Coverage: 37.5%
+- Denominator: 11 leaf commands
+- Covered: 6
+- Coverage: 54.5%
 
 ## Summary
 - TestDocs_CreateAndFetchWorkflow: proves `docs +create` and `docs +fetch`; key `t.Run(...)` proof points are `create as bot` and `fetch as bot`.
@@ -11,6 +11,8 @@
 - TestDocs_UpdateWorkflow: proves `docs +update` via `update-title-and-content as bot`, then re-fetches the same doc in `verify as bot` to assert persisted title/content changes.
 - TestDocs_DryRunDefaultsToV2OpenAPI: proves `docs +create`, `docs +fetch`, and `docs +update` dry-run all emit `/open-apis/docs_ai/v1/...` requests without MCP or `--api-version` guidance; its fetch case asserts fetch sends the default `extra_param`, and its update case asserts `--reference-map` is sent as request body `reference_map`.
 - TestDocs_CreateTitleDryRunPrependsContent: proves `docs +create --title` dry-run prepends an escaped `<title>...</title>` tag to request body `content`.
+- TestDocs_DryRunDefaultsToV2OpenAPI also proves `docs +history-list`, `docs +history-revert`, and `docs +history-revert-status` dry-run endpoint and query/body shapes.
+- TestDocs_HistoryWorkflow proves the guarded live history flow (`LARK_DOC_HISTORY_E2E=1`): create, update, list prior revisions, revert, poll status when needed, and fetch to verify reverted content.
 - Setup note: docs workflows create a Drive folder through `drive files create_folder` in `helpers_test.go`; that helper is external to the docs domain and is not counted here.
 - Blocked area: media and search shortcuts still need deterministic fixtures and local file orchestration.
 
@@ -20,6 +22,9 @@
 | --- | --- | --- | --- | --- | --- |
 | ✓ | docs +create | shortcut | docs/helpers_test.go::createDocWithRetry; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/create as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/create; docs_update_dryrun_test.go::TestDocs_CreateTitleDryRunPrependsContent | `--parent-token`; `--doc-format markdown`; `--content`; `--title` | helper asserts returned doc id from `data.document.document_id`; dry-run asserts title is prepended into request body content |
 | ✓ | docs +fetch | shortcut | docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflow/fetch as bot; docs_update_test.go::TestDocs_UpdateWorkflow/verify as bot; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/fetch as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/fetch | `--doc <docToken>`; `--doc-format markdown`; default `extra_param.enable_user_cite_reference_map=true` | |
+| ✓ | docs +history-list | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history list; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--page-size`; `--page-token` | live workflow gated by `LARK_DOC_HISTORY_E2E=1` |
+| ✓ | docs +history-revert | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history revert; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--history-version-id`; `--wait-timeout-ms` | live workflow gated by `LARK_DOC_HISTORY_E2E=1` |
+| ✓ | docs +history-revert-status | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history revert status; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--task-id` | live workflow polls only when revert returns `running` |
 | ✕ | docs +media-download | shortcut |  | none | no media fixture workflow yet |
 | ✕ | docs +media-insert | shortcut |  | none | requires deterministic upload fixture and rollback assertions |
 | ✕ | docs +media-preview | shortcut |  | none | requires deterministic media fixture |

tests/cli_e2e/docs/docs_history_workflow_test.go

@@ -0,0 +1,137 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package docs
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/larksuite/cli/tests/cli_e2e/drive"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+func TestDocs_HistoryWorkflow(t *testing.T) {
+	if os.Getenv("LARK_DOC_HISTORY_E2E") != "1" {
+		t.Skip("set LARK_DOC_HISTORY_E2E=1 to run docs history live workflow")
+	}
+	clie2e.SkipWithoutUserToken(t)
+
+	parentT := t
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)
+	t.Cleanup(cancel)
+
+	suffix := clie2e.GenerateSuffix()
+	folderName := "lark-cli-e2e-docs-history-folder-" + suffix
+	docTitle := "lark-cli-e2e-docs-history-" + suffix
+	originalMarker := "original history marker " + suffix
+	updatedMarker := "updated history marker " + suffix
+	const defaultAs = "user"
+
+	folderToken := drive.CreateDriveFolder(t, parentT, ctx, folderName, defaultAs, "")
+	docToken := createDocWithRetry(t, parentT, ctx, folderToken, docTitle, originalMarker, defaultAs)
+
+	updateResult, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"docs", "+update",
+			"--doc", docToken,
+			"--command", "overwrite",
+			"--doc-format", "markdown",
+			"--content", "# " + docTitle + "\n\n" + updatedMarker,
+		},
+		DefaultAs: defaultAs,
+	})
+	require.NoError(t, err)
+	updateResult.AssertExitCode(t, 0)
+	updateResult.AssertStdoutStatus(t, true)
+
+	fetchUpdated, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args:      []string{"docs", "+fetch", "--doc", docToken, "--doc-format", "markdown"},
+		DefaultAs: defaultAs,
+	})
+	require.NoError(t, err)
+	fetchUpdated.AssertExitCode(t, 0)
+	fetchUpdated.AssertStdoutStatus(t, true)
+	updatedContent := gjson.Get(fetchUpdated.Stdout, "data.document.content").String()
+	assert.Contains(t, updatedContent, updatedMarker)
+	currentRevision := gjson.Get(fetchUpdated.Stdout, "data.document.revision_id").Int()
+	require.Greater(t, currentRevision, int64(0), "stdout:\n%s", fetchUpdated.Stdout)
+
+	var revertHistoryVersionID string
+	require.Eventually(t, func() bool {
+		listResult, listErr := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"docs", "+history-list",
+				"--doc", docToken,
+				"--page-size", "20",
+			},
+			DefaultAs: defaultAs,
+		})
+		require.NoError(t, listErr)
+		listResult.AssertExitCode(t, 0)
+		listResult.AssertStdoutStatus(t, true)
+		for _, entry := range gjson.Get(listResult.Stdout, "data.entries").Array() {
+			revisionID := entry.Get("revision_id").Int()
+			historyVersionID := entry.Get("history_version_id").String()
+			if revisionID > 0 && revisionID < currentRevision && historyVersionID != "" {
+				revertHistoryVersionID = historyVersionID
+				return true
+			}
+		}
+		return false
+	}, 45*time.Second, 3*time.Second, "history list did not expose a prior revision")
+	require.NotEmpty(t, revertHistoryVersionID)
+
+	revertResult, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"docs", "+history-revert",
+			"--doc", docToken,
+			"--history-version-id", revertHistoryVersionID,
+			"--wait-timeout-ms", "30000",
+		},
+		DefaultAs: defaultAs,
+	})
+	require.NoError(t, err)
+	revertResult.AssertExitCode(t, 0)
+	revertResult.AssertStdoutStatus(t, true)
+
+	status := gjson.Get(revertResult.Stdout, "data.status").String()
+	taskID := gjson.Get(revertResult.Stdout, "data.task_id").String()
+	statusStdout := revertResult.Stdout
+	if status == "running" {
+		require.NotEmpty(t, taskID, "stdout:\n%s", revertResult.Stdout)
+		require.Eventually(t, func() bool {
+			statusResult, statusErr := clie2e.RunCmd(ctx, clie2e.Request{
+				Args: []string{
+					"docs", "+history-revert-status",
+					"--doc", docToken,
+					"--task-id", taskID,
+				},
+				DefaultAs: defaultAs,
+			})
+			require.NoError(t, statusErr)
+			statusResult.AssertExitCode(t, 0)
+			statusResult.AssertStdoutStatus(t, true)
+			statusStdout = statusResult.Stdout
+			status = gjson.Get(statusResult.Stdout, "data.status").String()
+			return status != "" && status != "running"
+		}, 60*time.Second, 5*time.Second, "history revert task did not finish")
+	}
+	require.Equal(t, "done", status, "status stdout:\n%s", statusStdout)
+
+	fetchReverted, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args:      []string{"docs", "+fetch", "--doc", docToken, "--doc-format", "markdown"},
+		DefaultAs: defaultAs,
+	})
+	require.NoError(t, err)
+	fetchReverted.AssertExitCode(t, 0)
+	fetchReverted.AssertStdoutStatus(t, true)
+	revertedContent := gjson.Get(fetchReverted.Stdout, "data.document.content").String()
+	assert.Contains(t, revertedContent, originalMarker)
+	assert.NotContains(t, revertedContent, updatedMarker)
+}

tests/cli_e2e/docs/docs_update_dryrun_test.go

@@ -26,7 +26,10 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 	tests := []struct {
 		name           string
 		args           []string
+		wantContains   []string
 		wantURL        string
+		wantParams     map[string]any
+		wantBody       map[string]any
 		wantExtraParam string
 		wantRefLabel   string
 	}{
@@ -37,7 +40,7 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 				"--content", "<title>Dry Run</title><p>hello</p>",
 				"--dry-run",
 			},
-			wantURL: "/open-apis/docs_ai/v1/documents",
+			wantContains: []string{"/open-apis/docs_ai/v1/documents"},
 		},
 		{
 			name: "create api-version v1 compatibility",
@@ -47,7 +50,7 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 				"--content", "<title>Dry Run</title><p>hello</p>",
 				"--dry-run",
 			},
-			wantURL: "/open-apis/docs_ai/v1/documents",
+			wantContains: []string{"/open-apis/docs_ai/v1/documents"},
 		},
 		{
 			name: "fetch",
@@ -56,7 +59,7 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 				"--doc", "doxcnDryRunE2E",
 				"--dry-run",
 			},
-			wantURL:        "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E/fetch",
+			wantContains:   []string{"/open-apis/docs_ai/v1/documents/doxcnDryRunE2E/fetch"},
 			wantExtraParam: `{"enable_user_cite_reference_map":true,"return_html5_block_data":true}`,
 		},
 		{
@@ -68,7 +71,7 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 				"--content", "<p>hello</p>",
 				"--dry-run",
 			},
-			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E",
+			wantContains: []string{"/open-apis/docs_ai/v1/documents/doxcnDryRunE2E"},
 		},
 		{
 			name: "update reference-map",
@@ -80,7 +83,7 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 				"--reference-map", `{"widget":{"r1":{"label":"widget-ref-value"}}}`,
 				"--dry-run",
 			},
-			wantURL:      "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E",
+			wantContains: []string{"/open-apis/docs_ai/v1/documents/doxcnDryRunE2E"},
 			wantRefLabel: "widget-ref-value",
 		},
 		{
@@ -92,7 +95,50 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 				"--block-id", "blkA,blkB,blkC",
 				"--dry-run",
 			},
-			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E",
+			wantContains: []string{"/open-apis/docs_ai/v1/documents/doxcnDryRunE2E"},
+		},
+		{
+			name: "history list",
+			args: []string{
+				"docs", "+history-list",
+				"--doc", "doxcnDryRunE2E",
+				"--page-size", "5",
+				"--page-token", "page_token_1",
+				"--dry-run",
+			},
+			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E/histories",
+			wantParams: map[string]any{
+				"page_size":  5,
+				"page_token": "page_token_1",
+			},
+		},
+		{
+			name: "history revert",
+			args: []string{
+				"docs", "+history-revert",
+				"--doc", "doxcnDryRunE2E",
+				"--history-version-id", "42",
+				"--wait-timeout-ms", "0",
+				"--dry-run",
+			},
+			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E/history/revert",
+			wantBody: map[string]any{
+				"history_version_id": "42",
+				"wait_timeout_ms":    0,
+			},
+		},
+		{
+			name: "history revert status",
+			args: []string{
+				"docs", "+history-revert-status",
+				"--doc", "doxcnDryRunE2E",
+				"--task-id", "task_1",
+				"--dry-run",
+			},
+			wantURL: "/open-apis/docs_ai/v1/documents/doxcnDryRunE2E/history/revert_status",
+			wantParams: map[string]any{
+				"task_id": "task_1",
+			},
 		},
 	}
 
@@ -106,10 +152,7 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 			result.AssertExitCode(t, 0)
 
 			combined := result.Stdout + "\n" + result.Stderr
-			for _, want := range []string{
-				tt.wantURL,
-				"docs_ai/v1",
-			} {
+			for _, want := range append(tt.wantContains, "docs_ai/v1") {
 				if !strings.Contains(combined, want) {
 					t.Fatalf("dry-run output missing %q\nstdout:\n%s\nstderr:\n%s", want, result.Stdout, result.Stderr)
 				}
@@ -120,6 +163,15 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 			if strings.Contains(combined, "--api-version") {
 				t.Fatalf("dry-run output should not ask for --api-version\nstdout:\n%s\nstderr:\n%s", result.Stdout, result.Stderr)
 			}
+			if tt.wantURL != "" {
+				require.Equal(t, tt.wantURL, gjson.Get(result.Stdout, "api.0.url").String(), "stdout:\n%s", result.Stdout)
+			}
+			for key, want := range tt.wantParams {
+				assertDryRunField(t, result.Stdout, "api.0.params."+key, want)
+			}
+			for key, want := range tt.wantBody {
+				assertDryRunField(t, result.Stdout, "api.0.body."+key, want)
+			}
 			if tt.wantExtraParam != "" {
 				extraParam := gjson.Get(result.Stdout, "api.0.body.extra_param").String()
 				require.JSONEq(t, tt.wantExtraParam, extraParam, "stdout:\n%s", result.Stdout)
@@ -132,6 +184,21 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 	}
 }
 
+func assertDryRunField(t *testing.T, stdout, path string, want any) {
+	t.Helper()
+
+	got := gjson.Get(stdout, path)
+	require.True(t, got.Exists(), "%s missing in stdout:\n%s", path, stdout)
+	switch want := want.(type) {
+	case int:
+		require.Equal(t, int64(want), got.Int(), "%s in stdout:\n%s", path, stdout)
+	case string:
+		require.Equal(t, want, got.String(), "%s in stdout:\n%s", path, stdout)
+	default:
+		t.Fatalf("unsupported dry-run assertion type %T for %s", want, path)
+	}
+}
+
 func TestDocs_CreateTitleDryRunPrependsContent(t *testing.T) {
 	// Fake creds are enough — dry-run short-circuits before any real API call.
 	t.Setenv("LARKSUITE_CLI_APP_ID", "app")

tests/cli_e2e/minutes/minutes_detail_dryrun_test.go

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestMinutesDetail_DryRunWaitReady(t *testing.T) {
+	setDryRunConfigEnv(t)
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"minutes", "+detail",
+			"--minute-tokens", "tok",
+			"--summary",
+			"--todo",
+			"--wait-ready",
+			"--dry-run",
+		},
+		DefaultAs: "user",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	output := result.Stdout
+	assert.True(t, strings.Contains(output, "/open-apis/minutes/v1/minutes/{minute_token}"), "dry-run should contain metadata API path, got: %s", output)
+	assert.True(t, strings.Contains(output, "/open-apis/minutes/v1/minutes/{minute_token}/artifacts"), "dry-run should contain artifacts API path, got: %s", output)
+}