docs: remove lark-slides chart critical

The stdout success envelope is {ok, identity, data, meta?} and carries no
top-level code/msg field, but wrappers following the raw OpenAPI convention
test code == 0 and misclassify every successful call as a failure. Around
write commands this defeats caller-side idempotency and causes duplicate
creates (see #1689).

Document the contract in ERROR_CONTRACT.md (success-envelope counterpart to
the error wire format), both READMEs (JSON Output Contract section), the
lark-shared skill (shared prerequisite for all skills), and add a success
response example to lark-task-create.md.

Closes #1689

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

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)),

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

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/drive/drive_permission_get_setting.go

@@ -1,226 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package drive
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"net/url"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-type drivePermissionGetSettingSpec struct {
-	Token string
-	Type  string
-}
-
-var drivePermissionGetSettingTypes = []string{
-	"doc", "sheet", "file", "wiki", "bitable", "docx",
-	"mindnote", "minutes", "slides", "folder",
-}
-
-var drivePermissionGetSettingURLPathToType = []struct {
-	Prefix string
-	Type   string
-}{
-	{"/drive/folder/", "folder"},
-	{"/docx/", "docx"},
-	{"/doc/", "doc"},
-	{"/sheets/", "sheet"},
-	{"/base/", "bitable"},
-	{"/bitable/", "bitable"},
-	{"/wiki/", "wiki"},
-	{"/file/", "file"},
-	{"/mindnotes/", "mindnote"},
-	{"/slides/", "slides"},
-	{"/minutes/", "minutes"},
-}
-
-func readDrivePermissionGetSettingSpec(runtime *common.RuntimeContext) (drivePermissionGetSettingSpec, error) {
-	rawToken := strings.TrimSpace(runtime.Str("token"))
-	explicitType := strings.ToLower(strings.TrimSpace(runtime.Str("type")))
-
-	if rawToken == "" {
-		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
-			errs.SubtypeInvalidArgument,
-			"--token is required",
-		).WithParam("--token")
-	}
-
-	if explicitType != "" && !drivePermissionGetSettingTypeAllowed(explicitType) {
-		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
-			errs.SubtypeInvalidArgument,
-			"invalid --type %q: allowed values are %s",
-			explicitType,
-			strings.Join(drivePermissionGetSettingTypes, ", "),
-		).WithParam("--type")
-	}
-
-	if strings.Contains(rawToken, "://") {
-		ref, ok := parseDrivePermissionGetSettingResourceURL(rawToken)
-		if !ok {
-			return drivePermissionGetSettingSpec{}, errs.NewValidationError(
-				errs.SubtypeInvalidArgument,
-				"unsupported --token URL %q: pass a recognized Lark Drive document/folder URL or a bare token with --type",
-				rawToken,
-			).WithParam("--token")
-		}
-		if explicitType != "" && explicitType != ref.Type {
-			return drivePermissionGetSettingSpec{}, errs.NewValidationError(
-				errs.SubtypeInvalidArgument,
-				"--type %q conflicts with URL path type %q; remove --type or use a matching value",
-				explicitType,
-				ref.Type,
-			).WithParam("--type")
-		}
-		if err := validate.ResourceName(ref.Token, "--token"); err != nil {
-			return drivePermissionGetSettingSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
-		}
-		return drivePermissionGetSettingSpec{Token: ref.Token, Type: ref.Type}, nil
-	}
-
-	if explicitType == "" {
-		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
-			errs.SubtypeInvalidArgument,
-			"--type is required when --token is a bare token (allowed: %s)",
-			strings.Join(drivePermissionGetSettingTypes, ", "),
-		).WithParam("--type")
-	}
-
-	if err := validate.ResourceName(rawToken, "--token"); err != nil {
-		return drivePermissionGetSettingSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
-	}
-	return drivePermissionGetSettingSpec{Token: rawToken, Type: explicitType}, nil
-}
-
-func parseDrivePermissionGetSettingResourceURL(rawURL string) (common.ResourceRef, bool) {
-	parsed, err := url.Parse(strings.TrimSpace(rawURL))
-	if err != nil || parsed.Hostname() == "" {
-		return common.ResourceRef{}, false
-	}
-
-	for _, mapping := range drivePermissionGetSettingURLPathToType {
-		if !strings.HasPrefix(parsed.Path, mapping.Prefix) {
-			continue
-		}
-		token := parsed.Path[len(mapping.Prefix):]
-		token = strings.TrimRight(token, "/")
-		if idx := strings.IndexByte(token, '/'); idx >= 0 {
-			token = token[:idx]
-		}
-		token = strings.TrimSpace(token)
-		if token == "" {
-			return common.ResourceRef{}, false
-		}
-		return common.ResourceRef{Type: mapping.Type, Token: token}, true
-	}
-
-	return common.ResourceRef{}, false
-}
-
-func drivePermissionGetSettingTypeAllowed(docType string) bool {
-	for _, allowed := range drivePermissionGetSettingTypes {
-		if docType == allowed {
-			return true
-		}
-	}
-	return false
-}
-
-func (s drivePermissionGetSettingSpec) url(runtime *common.RuntimeContext) string {
-	if runtime != nil && runtime.Config != nil {
-		if u := common.BuildResourceURL(runtime.Config.Brand, s.Type, s.Token); u != "" {
-			return u
-		}
-	}
-	return common.BuildResourceURL("", s.Type, s.Token)
-}
-
-func (s drivePermissionGetSettingSpec) params() map[string]interface{} {
-	return map[string]interface{}{"type": s.Type}
-}
-
-func (s drivePermissionGetSettingSpec) apiPath() string {
-	return drivePermissionPublicV2Path(s.Token)
-}
-
-func drivePermissionPublicV2Path(token string) string {
-	return fmt.Sprintf("/open-apis/drive/v2/permissions/%s/public", validate.EncodePathSegment(token))
-}
-
-func (s drivePermissionGetSettingSpec) output(runtime *common.RuntimeContext, data map[string]interface{}) map[string]interface{} {
-	permissionPublic := interface{}(data)
-	if nestedPermissionPublic := common.GetMap(data, "permission_public"); nestedPermissionPublic != nil {
-		permissionPublic = nestedPermissionPublic
-	}
-	return map[string]interface{}{
-		"permission_public": permissionPublic,
-	}
-}
-
-// DrivePermissionGetSetting queries permission_public settings for a Drive
-// document, file, wiki node, or folder.
-var DrivePermissionGetSetting = common.Shortcut{
-	Service:     "drive",
-	Command:     "+permission-get-setting",
-	Description: "Get public access, sharing, collaborator management, security, and comment permission settings",
-	Risk:        "read",
-	Scopes:      []string{"docs:permission.setting:read"},
-	AuthTypes:   []string{"user", "bot"},
-	HasFormat:   true,
-	Flags: []common.Flag{
-		{Name: "token", Desc: "target URL or bare token (doc/sheet/file/wiki/bitable/docx/mindnote/minutes/slides/folder)"},
-		{Name: "type", Desc: "target type; auto-inferred from URL, required for bare tokens", Enum: drivePermissionGetSettingTypes},
-	},
-	Tips: []string{
-		"--token accepts a Lark URL or bare token; pass --type when using a bare token.",
-		"Use --type folder for Drive folders. This shortcut reads the target's own permission settings; it does not recurse into child documents.",
-	},
-	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		_, err := readDrivePermissionGetSettingSpec(runtime)
-		return err
-	},
-	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		spec, err := readDrivePermissionGetSettingSpec(runtime)
-		if err != nil {
-			return common.NewDryRunAPI().Set("error", err.Error())
-		}
-		return common.NewDryRunAPI().
-			Desc("Get Drive permission settings").
-			GET(spec.apiPath()).
-			Params(spec.params())
-	},
-	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		spec, err := readDrivePermissionGetSettingSpec(runtime)
-		if err != nil {
-			return err
-		}
-
-		fmt.Fprintf(runtime.IO().ErrOut, "Getting permission settings for %s %s...\n", spec.Type, common.MaskToken(spec.Token))
-		data, err := runtime.CallAPITyped(
-			"GET",
-			spec.apiPath(),
-			spec.params(),
-			nil,
-		)
-		if err != nil {
-			return err
-		}
-
-		out := spec.output(runtime, data)
-		runtime.OutFormat(out, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "Type:  %s\n", spec.Type)
-			fmt.Fprintf(w, "Token: %s\n", spec.Token)
-			if url := spec.url(runtime); url != "" {
-				fmt.Fprintf(w, "URL:   %s\n", url)
-			}
-		})
-		return nil
-	},
-}

shortcuts/drive/drive_permission_get_setting_test.go

@@ -1,365 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package drive
-
-import (
-	"context"
-	"encoding/json"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-func newDrivePermissionGetSettingRuntime(t *testing.T, token, docType string) *common.RuntimeContext {
-	t.Helper()
-
-	cmd := &cobra.Command{Use: "drive +permission-get-setting"}
-	cmd.Flags().String("token", "", "")
-	cmd.Flags().String("type", "", "")
-	if token != "" {
-		if err := cmd.Flags().Set("token", token); err != nil {
-			t.Fatalf("set --token: %v", err)
-		}
-	}
-	if docType != "" {
-		if err := cmd.Flags().Set("type", docType); err != nil {
-			t.Fatalf("set --type: %v", err)
-		}
-	}
-	return common.TestNewRuntimeContext(cmd, driveTestConfig())
-}
-
-func TestDrivePermissionGetSettingSpecResolvesTargets(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name     string
-		token    string
-		docType  string
-		wantTok  string
-		wantType string
-	}{
-		{
-			name:     "folder URL",
-			token:    "https://example.feishu.cn/drive/folder/fldTok?from=share",
-			wantTok:  "fldTok",
-			wantType: "folder",
-		},
-		{
-			name:     "docx URL",
-			token:    "https://example.feishu.cn/docx/doxTok",
-			wantTok:  "doxTok",
-			wantType: "docx",
-		},
-		{
-			name:     "file URL",
-			token:    "https://example.feishu.cn/file/boxTok",
-			wantTok:  "boxTok",
-			wantType: "file",
-		},
-		{
-			name:     "wiki URL",
-			token:    "https://example.feishu.cn/wiki/wikTok",
-			wantTok:  "wikTok",
-			wantType: "wiki",
-		},
-		{
-			name:     "minutes URL",
-			token:    "https://example.feishu.cn/minutes/obTok",
-			wantTok:  "obTok",
-			wantType: "minutes",
-		},
-		{
-			name:     "mindnotes URL",
-			token:    "https://example.feishu.cn/mindnotes/mndTok",
-			wantTok:  "mndTok",
-			wantType: "mindnote",
-		},
-		{
-			name:     "bare folder token",
-			token:    " fldTok ",
-			docType:  " folder ",
-			wantTok:  "fldTok",
-			wantType: "folder",
-		},
-		{
-			name:     "bare file token",
-			token:    "boxTok",
-			docType:  "file",
-			wantTok:  "boxTok",
-			wantType: "file",
-		},
-		{
-			name:     "bare wiki token",
-			token:    "wikTok",
-			docType:  "wiki",
-			wantTok:  "wikTok",
-			wantType: "wiki",
-		},
-	}
-
-	for _, temp := range tests {
-		tt := temp
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
-			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
-			spec, err := readDrivePermissionGetSettingSpec(runtime)
-			if err != nil {
-				t.Fatalf("read spec: %v", err)
-			}
-			if spec.Token != tt.wantTok {
-				t.Fatalf("Token = %q, want %q", spec.Token, tt.wantTok)
-			}
-			if spec.Type != tt.wantType {
-				t.Fatalf("Type = %q, want %q", spec.Type, tt.wantType)
-			}
-		})
-	}
-}
-
-func TestDrivePermissionGetSettingSpecValidationErrorsAreTyped(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name        string
-		token       string
-		docType     string
-		wantParam   string
-		wantMessage string
-	}{
-		{
-			name:        "missing token",
-			wantParam:   "--token",
-			wantMessage: "--token is required",
-		},
-		{
-			name:        "bare token without type",
-			token:       "doxTok",
-			wantParam:   "--type",
-			wantMessage: "--type is required",
-		},
-		{
-			name:        "unsupported URL",
-			token:       "https://example.feishu.cn/calendar/calTok",
-			wantParam:   "--token",
-			wantMessage: "unsupported --token URL",
-		},
-		{
-			name:        "URL type conflict",
-			token:       "https://example.feishu.cn/docx/doxTok",
-			docType:     "sheet",
-			wantParam:   "--type",
-			wantMessage: "conflicts with URL path type",
-		},
-		{
-			name:        "invalid bare token",
-			token:       "../bad",
-			docType:     "folder",
-			wantParam:   "--token",
-			wantMessage: "--token",
-		},
-		{
-			name:        "invalid type",
-			token:       "doxTok",
-			docType:     "comment",
-			wantParam:   "--type",
-			wantMessage: "invalid --type",
-		},
-	}
-
-	for _, temp := range tests {
-		tt := temp
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
-			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
-			_, err := readDrivePermissionGetSettingSpec(runtime)
-			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 != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
-				t.Fatalf("problem = %s/%s, want validation/invalid_argument", problem.Category, problem.Subtype)
-			}
-			if validationErr, ok := err.(*errs.ValidationError); ok {
-				if validationErr.Param != tt.wantParam {
-					t.Fatalf("param = %q, want %q", validationErr.Param, tt.wantParam)
-				}
-			} else {
-				t.Fatalf("error type = %T, want *errs.ValidationError", err)
-			}
-			if !strings.Contains(err.Error(), tt.wantMessage) {
-				t.Fatalf("error = %q, want substring %q", err.Error(), tt.wantMessage)
-			}
-		})
-	}
-}
-
-func TestDrivePermissionGetSettingDryRunIncludesGETRequest(t *testing.T) {
-	t.Parallel()
-
-	tests := []struct {
-		name     string
-		token    string
-		docType  string
-		wantURL  string
-		wantType string
-	}{
-		{
-			name:     "folder URL",
-			token:    "https://example.feishu.cn/drive/folder/fldTok",
-			wantURL:  "/open-apis/drive/v2/permissions/fldTok/public",
-			wantType: "folder",
-		},
-		{
-			name:     "bare folder token",
-			token:    "fldTok",
-			docType:  "folder",
-			wantURL:  "/open-apis/drive/v2/permissions/fldTok/public",
-			wantType: "folder",
-		},
-		{
-			name:     "docx URL",
-			token:    "https://example.feishu.cn/docx/doxTok",
-			wantURL:  "/open-apis/drive/v2/permissions/doxTok/public",
-			wantType: "docx",
-		},
-		{
-			name:     "bare wiki token",
-			token:    "wikTok",
-			docType:  "wiki",
-			wantURL:  "/open-apis/drive/v2/permissions/wikTok/public",
-			wantType: "wiki",
-		},
-		{
-			name:     "file URL",
-			token:    "https://example.feishu.cn/file/boxTok",
-			wantURL:  "/open-apis/drive/v2/permissions/boxTok/public",
-			wantType: "file",
-		},
-		{
-			name:     "minutes URL",
-			token:    "https://example.feishu.cn/minutes/obTok",
-			wantURL:  "/open-apis/drive/v2/permissions/obTok/public",
-			wantType: "minutes",
-		},
-		{
-			name:     "mindnotes URL",
-			token:    "https://example.feishu.cn/mindnotes/mndTok",
-			wantURL:  "/open-apis/drive/v2/permissions/mndTok/public",
-			wantType: "mindnote",
-		},
-	}
-
-	for _, temp := range tests {
-		tt := temp
-		t.Run(tt.name, func(t *testing.T) {
-			t.Parallel()
-
-			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
-			dry := DrivePermissionGetSetting.DryRun(context.Background(), runtime)
-			if dry == nil {
-				t.Fatal("DryRun returned nil")
-			}
-			data, err := json.Marshal(dry)
-			if err != nil {
-				t.Fatalf("marshal dry-run: %v", err)
-			}
-			out := string(data)
-			for _, want := range []string{
-				`"` + tt.wantURL + `"`,
-				`"GET"`,
-				`"type":"` + tt.wantType + `"`,
-			} {
-				if !strings.Contains(out, want) {
-					t.Fatalf("dry-run output missing %q:\n%s", want, out)
-				}
-			}
-			if strings.Contains(out, `"folder_token"`) {
-				t.Fatalf("dry-run output contains folder_token, want omitted:\n%s", out)
-			}
-		})
-	}
-}
-
-func TestDrivePermissionGetSettingExecutePreservesPermissionPublic(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/drive/v2/permissions/doxTok/public?type=docx",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"data": map[string]interface{}{
-				"permission_public": map[string]interface{}{
-					"link_share_entity":          "closed",
-					"external_access_entity":     "closed",
-					"security_entity":            "anyone_can_view",
-					"comment_entity":             "anyone_can_view",
-					"share_entity":               "anyone",
-					"manage_collaborator_entity": "collaborator_can_view",
-					"lock_switch":                false,
-					"server_future_field":        "preserved",
-				},
-			},
-		},
-	})
-
-	err := mountAndRunDrive(t, DrivePermissionGetSetting, []string{
-		"+permission-get-setting",
-		"--token", "doxTok",
-		"--type", "docx",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	data := decodeDriveEnvelope(t, stdout)
-	for _, key := range []string{"type", "token", "url"} {
-		if _, ok := data[key]; ok {
-			t.Fatalf("data[%s] = %#v, want field omitted", key, data[key])
-		}
-	}
-	permissionPublic, _ := data["permission_public"].(map[string]interface{})
-	if permissionPublic == nil {
-		t.Fatalf("permission_public missing in output: %#v", data)
-	}
-	for key, want := range map[string]interface{}{
-		"link_share_entity":          "closed",
-		"external_access_entity":     "closed",
-		"security_entity":            "anyone_can_view",
-		"comment_entity":             "anyone_can_view",
-		"share_entity":               "anyone",
-		"manage_collaborator_entity": "collaborator_can_view",
-		"lock_switch":                false,
-		"server_future_field":        "preserved",
-	} {
-		if permissionPublic[key] != want {
-			t.Fatalf("permission_public[%s] = %#v, want %#v", key, permissionPublic[key], want)
-		}
-	}
-}
-
-func TestDrivePermissionGetSettingDeclaresScopeAndIdentities(t *testing.T) {
-	t.Parallel()
-
-	if !reflect.DeepEqual(DrivePermissionGetSetting.Scopes, []string{"docs:permission.setting:read"}) {
-		t.Fatalf("Scopes = %v, want docs:permission.setting:read", DrivePermissionGetSetting.Scopes)
-	}
-	if !reflect.DeepEqual(DrivePermissionGetSetting.AuthTypes, []string{"user", "bot"}) {
-		t.Fatalf("AuthTypes = %v, want [user bot]", DrivePermissionGetSetting.AuthTypes)
-	}
-}

shortcuts/drive/shortcuts.go

@@ -31,7 +31,6 @@ func Shortcuts() []common.Shortcut {
 		DriveTaskResult,
 		DriveApplyPermission,
 		DriveMemberAdd,
-		DrivePermissionGetSetting,
 		DriveSecureLabelList,
 		DriveSecureLabelUpdate,
 		DriveSearch,

shortcuts/drive/shortcuts_test.go

@@ -37,7 +37,6 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 		"+task_result",
 		"+apply-permission",
 		"+member-add",
-		"+permission-get-setting",
 		"+secure-label-list",
 		"+secure-label-update",
 		"+search",

shortcuts/slides/slides_screenshot.go

@@ -22,7 +22,10 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-const defaultSlidesScreenshotDir = ".lark-slides/screenshots"
+const (
+	defaultSlidesScreenshotDir = ".lark-slides/screenshots"
+	maxSlidesPerScreenshot     = 10
+)
 
 var unsafeScreenshotFileCharRegex = regexp.MustCompile(`[^A-Za-z0-9._-]+`)
 
@@ -32,7 +35,7 @@ var unsafeScreenshotFileCharRegex = regexp.MustCompile(`[^A-Za-z0-9._-]+`)
 var SlidesScreenshot = common.Shortcut{
 	Service:     "slides",
 	Command:     "+screenshot",
-	Description: "Save slide screenshots to local files without printing Base64 image data",
+	Description: "Save up to 10 slide screenshots to local files without printing Base64 image data",
 	Risk:        "read",
 	Scopes:      []string{},
 	// The screenshot API is allowlist-gated for only a few apps, so do not
@@ -42,8 +45,8 @@ var SlidesScreenshot = common.Shortcut{
 	AuthTypes:         []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "presentation", Desc: "xml_presentation_id, slides URL, or wiki URL that resolves to slides; list mode only"},
-		{Name: "slide-id", Type: "string_array", Desc: "slide page identifier (repeat for multiple slides)"},
-		{Name: "slide-number", Type: "int_array", Desc: "slide page number (repeat for multiple slides)"},
+		{Name: "slide-id", Type: "string_array", Desc: "slide page identifier (repeat for multiple slides; max 10 pages per request)"},
+		{Name: "slide-number", Type: "int_array", Desc: "slide page number (repeat for multiple slides; max 10 pages per request)"},
 		{Name: "content", Desc: "slide XML content to render directly instead of fetching existing slides", Input: []string{common.File, common.Stdin}},
 		{Name: "output-dir", Default: defaultSlidesScreenshotDir, Desc: "relative directory for saved screenshots"},
 		{Name: "output-name", Desc: "file name stem for --content render output"},
@@ -70,12 +73,17 @@ var SlidesScreenshot = common.Shortcut{
 					return err
 				}
 			}
-			if _, err := normalizeSlideNumbers(runtime.IntArray("slide-number")); err != nil {
+			slideIDs := normalizeSlideIDs(runtime.StrArray("slide-id"))
+			slideNumbers, err := normalizeSlideNumbers(runtime.IntArray("slide-number"))
+			if err != nil {
 				return err
 			}
-			if !hasSlideScreenshotSelector(runtime) {
+			if len(slideIDs) == 0 && len(slideNumbers) == 0 {
 				return slidesScreenshotFlagErrorf("--slide-id or --slide-number is required")
 			}
+			if err := validateSlidesScreenshotSelectorLimit(len(slideIDs) + len(slideNumbers)); err != nil {
+				return err
+			}
 		}
 		if _, err := validateScreenshotOutputDir(runtime, runtime.Str("output-dir")); err != nil {
 			return err
@@ -98,6 +106,9 @@ var SlidesScreenshot = common.Shortcut{
 		if len(slideIDs) == 0 && len(slideNumbers) == 0 {
 			return common.NewDryRunAPI().Set("error", "--slide-id or --slide-number is required")
 		}
+		if err := validateSlidesScreenshotSelectorLimit(len(slideIDs) + len(slideNumbers)); err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
 
 		presentationID := ref.Token
 		dry := common.NewDryRunAPI()
@@ -145,6 +156,9 @@ var SlidesScreenshot = common.Shortcut{
 		if len(slideIDs) == 0 && len(slideNumbers) == 0 {
 			return slidesScreenshotFlagErrorf("--slide-id or --slide-number is required")
 		}
+		if err := validateSlidesScreenshotSelectorLimit(len(slideIDs) + len(slideNumbers)); err != nil {
+			return err
+		}
 		outputDir := runtime.Str("output-dir")
 		safeOutputDir, err := ensureScreenshotOutputDir(runtime, outputDir)
 		if err != nil {
@@ -267,8 +281,11 @@ func normalizeSlideNumbers(values []int) ([]int, error) {
 	return out, nil
 }
 
-func hasSlideScreenshotSelector(runtime *common.RuntimeContext) bool {
-	return len(normalizeSlideIDs(runtime.StrArray("slide-id"))) > 0 || len(runtime.IntArray("slide-number")) > 0
+func validateSlidesScreenshotSelectorLimit(count int) error {
+	if count > maxSlidesPerScreenshot {
+		return slidesScreenshotFlagErrorf("too many slide selectors: got %d, maximum is %d; request at most 10 pages at a time", count, maxSlidesPerScreenshot)
+	}
+	return nil
 }
 
 func slidesScreenshotFlagErrorf(format string, args ...interface{}) error {

shortcuts/slides/slides_screenshot_test.go

@@ -271,6 +271,33 @@ func TestSlidesScreenshotListRequiresSelector(t *testing.T) {
 	}
 }
 
+func TestSlidesScreenshotListRejectsMoreThanTenSelectors(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
+
+	err := runSlidesShortcut(t, f, stdout, SlidesScreenshot, []string{
+		"+screenshot",
+		"--presentation", "pres_abc",
+		"--slide-number", "1",
+		"--slide-number", "2",
+		"--slide-number", "3",
+		"--slide-number", "4",
+		"--slide-number", "5",
+		"--slide-number", "6",
+		"--slide-number", "7",
+		"--slide-number", "8",
+		"--slide-number", "9",
+		"--slide-number", "10",
+		"--slide-number", "11",
+		"--as", "user",
+	})
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "request at most 10 pages at a time") {
+		t.Fatalf("error = %v, want max 10 pages guidance", err)
+	}
+}
+
 func TestSlidesScreenshotRenderContentWritesFile(t *testing.T) {
 	dir := t.TempDir()
 	withSlidesTestWorkingDir(t, dir)

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

@@ -45,13 +45,15 @@ lark-cli calendar +agenda --as user
 | 场景 | 前置要求 |
 |------|----------|
 | 预约日程/会议、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) |
-| 编辑已有日程 | 先定位目标日程 `event_id`；若是重复性日程，必须定位到具体实例的 `event_id`（禁止使用原重复日程 ID） |
+| 编辑已有日程 | 先定位目标日程 `event_id` |
+| 编辑/删除重复性日程 | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，按操作范围（仅此次/全部/此次及后续）执行 |
 | 删除/修改后验证 | 等待 2 秒再查询（API 最终一致性），不要告知用户你等待了 |
 | 调用任何 Shortcut | 先读其对应 reference 文档 |
 
 ## 核心概念
 
-- **日程实例（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），不能脱离日程单独预定。
@@ -71,6 +73,7 @@ lark-cli calendar +agenda --as user
 | 从日程获取关联的视频会议 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) |
+| 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，确认操作范围后执行 |
 
 ## 任务类型分流
 

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

@@ -47,6 +47,7 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 > 自动设置 `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 命令）
 
@@ -72,9 +73,16 @@ lark-cli calendar events create \
 lark-cli schema calendar.event.attendees.create
 ## 添加参会人
 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"}]}'
 
+## 添加需要审批的会议室（approval_reason 最大 200 字符）
+lark-cli calendar event.attendees create \
+  --as user \
+  --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \
+  --data '{"attendees": [{"type": "resource", "room_id": "omm_xxx", "approval_reason": "申请原因"}]}'
+
 # 可选第三步（推荐）：若第二步失败，回滚删除空日程
 ## 查看完整参数定义
 lark-cli schema calendar.events.delete

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-update.md

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

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

@@ -23,7 +23,7 @@
 1. 分析用户需求：受众、目的、范围
 2. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
 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 生命周期」），否则反复锚同一个标题会让段落顺序颠倒
@@ -41,6 +41,7 @@
 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` 插入
 
-### 步骤四：专项校验（按需执行）
+### 步骤四：专项校验
 
-9. 仅当用户预期需要校验字数时，才读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；否则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现结果
+9. **字数门禁**：如果用户给出任何明确字数要求（如“700-800 字”“1000 字左右”“不少于 500 字”“控制在 800 字以内”），本步骤必须执行，不属于按需项。读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；未得到脚本统计结果前，不得向用户声明“符合字数要求”。若没有明确字数要求，则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现目标区间、`word_count` 和达标结论
+10. **重复标题检查**：文档生成后，检查文档标题和正文第一个标题块是否重复；若重复，删除或改写正文第一个标题块，避免读者看到同一标题连续出现

skills/lark-drive/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lark-drive
 version: 1.0.0
-description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、查询权限设置、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。"
+description: "飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -22,7 +22,6 @@ metadata:
 
 - 用户要**复制文档 / 创建副本 / 另存为副本**时，使用 `lark-cli drive files copy`。先用 `lark-cli schema drive.files.copy --format json` 确认参数；如果来源是 wiki URL/token，先用 `lark-cli drive +inspect` 获取底层 `token` 和 `type`，不要把 wiki token 直接当 `file_token`。`params.file_token` 传源文档 token，`data.folder_token` 传目标文件夹 token，`data.name` 传副本名称，`data.type` 传源文件类型（如 `docx` / `sheet` / `bitable` / `slides`）。示例：`lark-cli drive files copy --params '{"file_token":"<DOC_TOKEN>"}' --data '{"folder_token":"<FOLDER_TOKEN>","name":"<COPY_NAME>","type":"docx"}'`。如返回 `confirmation_required`，按 `lark-shared` 高风险审批协议向用户确认后，在原命令末尾追加 `--yes` 重试。
 - 用户要**检查 / 治理文档权限、公开范围、链接分享、外部访问、复制下载权限、密级标签、owner 转移**，或要“权限风险报告、收紧权限、申请查看 / 编辑权限、转移 / 批量转移 owner”，必须先阅读 [`references/lark-drive-workflow.md`](references/lark-drive-workflow.md)，再按其中 `Workflow Registry` 进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
-- 用户要**查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置**，优先使用 `lark-cli drive +permission-get-setting`；它只读取目标自身设置，不递归审计文件夹子文档权限。裸 token 必须显式传 `--type`。
 - 用户要**整理云盘 / 文件夹 / 文档库 / 知识库 / 个人文档库**，或要“盘点目录结构、找出未归档/临时/重复/空目录、生成整理方案”，必须先阅读 [`references/lark-drive-workflow-knowledge-organize.md`](references/lark-drive-workflow-knowledge-organize.md)。默认只生成方案；创建目录、移动资源、申请权限都必须单独确认。
 - 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--created-by-me`，原始创建者语义）、"我负责/owner 的"（→ `--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
 - 用户要**根据文档评论定位正文位置**，例如 根据评论 review 文档、根据评论内容回看文档、区分多处相同引用文本时，对于 docx 类型（`file_type=docx`）的文档支持通过 `need_relation=true` 返回评论位置，其他类型暂不支持，具体用法需要先阅读 [`references/lark-drive-comment-location.md`](references/lark-drive-comment-location.md) 了解。
@@ -30,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`。
@@ -103,11 +103,11 @@ 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 次，仍失败就停止并报告冲突 |
 
 ### 权限能力入口
 
 - 用户要管理 Drive 文档/文件协作者、公开权限、授权当前应用访问文档，或处理 `permission.public.patch` 的 `91009` / `91010` / `91011` / `91012` 错误时，先读 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。
-- 用户要查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置，使用 [`+permission-get-setting`](references/lark-drive-permission-get-setting.md)；如果要递归审计文件夹下子文档权限，再进入 [`permission_governance`](references/lark-drive-workflow-permission-governance.md) workflow。
 - 用户只是没有访问权限并希望向 owner 申请访问，优先使用 [`+apply-permission`](references/lark-drive-apply-permission.md)。
 - 普通 scope、身份或登录问题仍按 [`lark-shared`](../lark-shared/SKILL.md) 处理；不要把租户安全策略、对外分享、密级拦截简单归类为缺 scope。
 
@@ -150,7 +150,6 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）
 | [`+inspect`](references/lark-drive-inspect.md) | 检视 URL 的类型、标题和 canonical token；wiki URL 会自动解包到底层文档。 |
 | [`+apply-permission`](references/lark-drive-apply-permission.md) | 以 user 身份向文档 owner 申请访问权限。 |
 | [`+member-add`](references/lark-drive-member-add.md) | 添加一个或最多 10 个 Drive 文档、文件、文件夹或 wiki 节点协作者/授权成员；封装 Drive permission member create/batch_create，真实写入需要 `--yes`。 |
-| [`+permission-get-setting`](references/lark-drive-permission-get-setting.md) | 查询文件、文件夹或云文档自身的公开访问、分享、协作者管理、安全与评论权限设置；支持 URL 或裸 token + `--type`；不递归读取文件夹子文档权限。 |
 | [`+secure-label-list`](references/lark-drive-secure-label.md) | 列出当前用户可用的密级标签。 |
 | [`+secure-label-update`](references/lark-drive-secure-label.md) | 更新 Drive 文件或文档的密级标签。 |
 

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-drive/references/lark-drive-workflow-permission-governance-commands.md

@@ -15,8 +15,6 @@
 lark-cli drive +inspect --url '<url>' --as user --format json
 ```
 
-`drive +inspect` 不支持 Drive folder。`/drive/folder/<folder_token>` 直接解析为 `type=folder` + `token=<folder_token>`；需要读取文件夹自身权限设置时使用 `drive +permission-get-setting --token '<folder_token>' --type folder`。
-
 `/wiki/space/<space_id>` URL 是 Wiki space 范围，不要用 `drive +inspect` 当作单文档解析；直接提取 `space_id` 后进入 `DISCOVER_TARGETS`。
 
 ## 目标发现
@@ -63,27 +61,11 @@ lark-cli drive metas batch_query \
   --as user --format json
 ```
 
-读取权限设置：
+读取 public permission：
 
 ```bash
-lark-cli drive +permission-get-setting \
-  --token '<url-or-token>' --type '<type>' \
-  --as user --format json
-```
-
-裸 folder token 必须显式传 `--type folder`：
-
-```bash
-lark-cli drive +permission-get-setting \
-  --token '<folder_token>' --type folder \
-  --as user --format json
-```
-
-通过 URL 读取权限设置时可以省略 `--type`：
-
-```bash
-lark-cli drive +permission-get-setting \
-  --token '<url>' \
+lark-cli drive permission.public get \
+  --params '{"token":"<token>","type":"<type>"}' \
   --as user --format json
 ```
 

skills/lark-drive/references/lark-drive-workflow-permission-governance-outputs.md

@@ -27,7 +27,7 @@
 - 多目标明确列表默认输出逐目标诊断摘要；不要因为目标数大于 1 就套用容器递归发现报告。
 - 用户可见结论默认跟随用户当前语言。用户用中文提问时输出中文，用户用英文提问时输出英文；混合语言时跟随主要语言。
 - 单目标公开性判断默认输出业务表达，不直接展示 `link_share_entity`、`external_access_entity`、`external_access` 等底层字段名；只有用户要求 raw evidence、排障，或完整清单 / artifact 场景才展示底层字段。
-- 中文用户可见输出中，`permission_public` / `public permission` 默认译为“目标公共访问和协作权限设置”；可在摘要里简称“公共访问与协作设置”。优先按实际返回字段解释公开访问、分享、协作者管理、安全与评论设置；复制内容、创建副本、打印、下载等字段只有在当前 CLI schema 和实际响应返回时才可判断。只有命令名、schema 字段、raw evidence、排障信息和完整 artifact 字段名保留英文原文。
+- 中文用户可见输出中，`permission_public` / `public permission` 默认译为“文档公共访问和协作权限设置”；可在摘要里简称“公共访问与协作设置”。它在官方语义中包含链接分享、对外分享、协作者管理、复制内容、创建副本、打印、下载和评论；具体可判断字段以当前 CLI schema 和实际响应为准。只有命令名、schema 字段、raw evidence、排障信息和完整 artifact 字段名保留英文原文。
 - 容器目标默认输出安全诊断报告摘要：一句话结论、覆盖情况、风险分级、优先处理对象、建议下一步和剩余限制。
 - 容器目标不要把风险按数量机械排序；外部公开、允许对外分享、缺失密级标签优先于复制 / 下载 / 评论这类依赖策略的候选项。
 - 用户没有提供明确 policy 时，使用“候选风险 / 待复核 / 待策略确认”，不要写“违规 / 已泄露 / 已外部访问”。
@@ -36,7 +36,7 @@
 - 当摘要未展示全部风险对象时，必须明确“完整清单包含 <count> 条”，并提供生成 Markdown / CSV / 飞书文档风险清单或整改 dry-run 的下一步。
 - 只要发现需要处理的对象，最终回复必须给出可执行下一步 CTA。不能因为默认只读，就只报告风险后结束。
 - 完整风险清单是后续治理选择的输入；Markdown / CSV / 飞书文档报告必须使用同一套字段和稳定 `risk_id`。
-- 写入前必须使用确认模板；权限申请、目标公共访问和协作权限设置修改、owner 转移、密级标签更新分别确认。
+- 写入前必须使用确认模板；权限申请、文档公共访问和协作权限设置修改、owner 转移、密级标签更新分别确认。
 - 最终回复必须包含已完成事项、验证结果和剩余限制；异步权限申请审批不能表述为已完成授权。
 
 ## Semantic Rendering
@@ -75,7 +75,7 @@
 | `lock_switch=true` | `lock_state=locked_not_inheriting` | 已限制权限，不再继承父级页面权限 | The node is locked and no longer inherits parent-page permissions |
 | `lock_switch=false` | `lock_state=not_locked_or_inheriting` | 未限制权限，可能继承父级页面权限 | The node is not locked and may inherit parent-page permissions |
 | field absent / unsupported | `<state>=unknown` | 当前 schema 未返回，无法判断 | The current schema did not return this field, so it is unknown |
-| `check_scope=current_public_permission_only` | `check_scope=current_public_permission_only` | 本次判断的是当前目标公共访问和协作权限设置，不是协作者名单或历史权限变更审计 | This check covers the target's current public access and collaboration settings, not collaborator-list or historical permission-change auditing |
+| `check_scope=current_public_permission_only` | `check_scope=current_public_permission_only` | 本次判断的是当前文档公共访问和协作权限设置，不是协作者名单或历史权限变更审计 | This check covers current public access and collaboration settings, not collaborator-list or historical permission-change auditing |
 | `sec_label_name` missing | `sec_label=missing` | 缺少密级标签 | Security label is missing |
 
 ## 定位与治理动作
@@ -165,7 +165,7 @@ Evidence fields:
 
 覆盖情况：
 - 用户提供目标：<input_target_count>；成功解析：<resolved_count>
-- 成功读取目标公共访问和协作权限设置：<permission_checked_count>；读取失败 / 不支持 / 无权限：<failed_or_unsupported_count>
+- 成功读取文档公共访问和协作权限设置：<permission_checked_count>；读取失败 / 不支持 / 无权限：<failed_or_unsupported_count>
 
 逐目标结果（1-10 个目标默认全部展示；超过 10 个时按 `摘要清单展开规则` 展示，并提示生成完整风险清单）：
 
@@ -233,7 +233,7 @@ URL：<url-or-token-if-url-unavailable>
 
 覆盖情况：
 - 当前身份可见目标：<visible_count>
-- 已成功检查目标公共访问和协作权限设置：<permission_checked_count>
+- 已成功检查文档公共访问和协作权限设置：<permission_checked_count>
 - 读取失败 / 已删除 / 无权限：<failed_count>
 - 未覆盖能力：<collaborator_list / inheritance / audit_log / view_records / none>
 
@@ -355,8 +355,8 @@ Agent 必须回复：
 - 字段变更：
   - <risk_id> <path> (<url-or-token>): <field> <old> -> <new>
 - 跳过项：<unsupported / no manage_public / unsupported type / missing policy>
-- 验证方式：执行后重新读取 <元数据 / 目标公共访问和协作权限设置>
-- 有限回滚范围：<目标公共访问和协作权限设置快照字段 / 不适用>
+- 验证方式：执行后重新读取 <元数据 / 文档公共访问和协作权限设置>
+- 有限回滚范围：<文档公共访问和协作权限设置快照字段 / 不适用>
 
 请确认是否进入写入确认。
 ```
@@ -407,8 +407,8 @@ Agent 必须回复：
 - 风险：<risk_level>
 - 字段变更：
   - <field>: <old> -> <new>
-- 验证方式：执行后重新读取 <元数据 / 目标公共访问和协作权限设置>
-- 有限回滚材料：<目标公共访问和协作权限设置快照 / 不适用>
+- 验证方式：执行后重新读取 <元数据 / 文档公共访问和协作权限设置>
+- 有限回滚材料：<文档公共访问和协作权限设置快照 / 不适用>
 
 请确认是否执行。
 ```
@@ -419,6 +419,6 @@ Agent 必须回复：
 已完成：<read checks / writes>
 验证：<fresh read result or async permission-request approval note>
 清单状态：<risk_id status updates / not applicable>
-回滚材料：<目标公共访问和协作权限设置快照 / 不适用>
+回滚材料：<文档公共访问和协作权限设置快照 / 不适用>
 剩余限制：<unsupported_checks / partial facts / approvals>
 ```

skills/lark-drive/references/lark-drive-workflow-permission-governance.md

@@ -38,7 +38,7 @@ Risk / Structure: `R2` / `S2`
 - 目录组织、迁移、归档或清理；这类需求应使用知识整理 workflow。
 - 内容审查、过期内容判断或知识质量评分。
 - backup owner 补充、部门 / 项目负责人绑定、协作者创建 / 撤销、成员列表审计；本 workflow 只支持把 owner 转移给每个目标明确指定的新 owner，不建模 backup owner 或负责人绑定关系。
-- 文件夹自身公开权限审计或修复。文件夹自身权限设置可以用 `drive +permission-get-setting` 读取；写入是否支持必须以运行时 schema 和明确需求为准，不能猜测执行 `patch type=folder`。
+- 文件夹自身公开权限审计或修复。`drive permission.public get` / `patch` 不支持 `type=folder`；必须记录到 `unsupported_checks`，然后继续读取文件夹下其他支持的文档事实。
 - 当前身份无法枚举到的不可见文档的完整发现；只能处理已发现目标，或用户显式提供的 URL / token。
 - 未按范围确认的批量写入。
 
@@ -53,7 +53,7 @@ Risk / Structure: `R2` / `S2`
 | `PARSE_INTENT` | 本文件、[`lark-drive-workflow.md`](lark-drive-workflow.md)、[`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) |
 | `TARGET_INSPECT` | [`lark-drive-inspect.md`](lark-drive-inspect.md) |
 | `DISCOVER_TARGETS` | 容器范围时读取 [`../../lark-wiki/references/lark-wiki-node-list.md`](../../lark-wiki/references/lark-wiki-node-list.md) 或 [`lark-drive-files-list.md`](lark-drive-files-list.md) |
-| `FACT_READ` | `lark-cli schema drive.metas.batch_query`；涉及权限设置读取时使用 `drive +permission-get-setting`；涉及活跃度、访问复核或生命周期判断时再读取 `lark-cli schema drive.file.statistics.get` 和 `lark-cli schema drive.file.view_records.list` |
+| `FACT_READ` | `lark-cli schema drive.metas.batch_query`；涉及公开权限时再读取 `lark-cli schema drive.permission.public.get`；涉及活跃度、访问复核或生命周期判断时再读取 `lark-cli schema drive.file.statistics.get` 和 `lark-cli schema drive.file.view_records.list` |
 | `RISK_ASSESS` | 本文件的 `Risk Classification` |
 | `EXEC_CONFIRM` | 只为用户选择的动作读取 [`lark-drive-apply-permission.md`](lark-drive-apply-permission.md)、[`lark-drive-secure-label.md`](lark-drive-secure-label.md)，或 `lark-cli schema drive.permission.public.patch` / `lark-cli schema drive.permission.members.transfer_owner`；需要确认模板时读取 [`lark-drive-workflow-permission-governance-outputs.md`](lark-drive-workflow-permission-governance-outputs.md) |
 | `EXECUTE` | 复用 `EXEC_CONFIRM` 已加载且已确认的写命令上下文 |
@@ -76,9 +76,9 @@ Risk / Structure: `R2` / `S2`
 | State | Protocol Step | Agent MUST Do | User-Facing Output | wait_for_user | Next State |
 |-------|---------------|---------------|--------------------|---------------|------------|
 | `PARSE_INTENT` | `route` / `scope` | 解析 intent、target scope、desired policy，以及只读审计、单目标公开性判断、权限申请、owner 转移还是修复模式；单目标公开性判断设置 `intent=public_exposure_check`、`target_scope=single_resource` | 范围确认；如果缺少目标、新 owner 或期望动作，只问一个澄清问题 | 缺少 target / new owner / action，或容器范围需要用户确认时为 `true` | `TARGET_INSPECT` |
-| `TARGET_INSPECT` | `scope` | 解析单资源、明确列表、Wiki space / node、Drive folder；Drive folder 直接从 URL 路径或显式 `type=folder` 解析，不调用 `drive +inspect`；保留原始 URL、scope type、canonical token/type | 目标范围表，包含 scope、title/type/token status | 除非解析失败，否则为 `false` | `DISCOVER_TARGETS` or `FACT_READ` |
+| `TARGET_INSPECT` | `scope` | 解析单资源、明确列表、Wiki space / node、Drive folder；保留原始 URL、scope type、canonical token/type | 目标范围表，包含 scope、title/type/token status | 除非解析失败，否则为 `false` | `DISCOVER_TARGETS` or `FACT_READ` |
 | `DISCOVER_TARGETS` | `scope` / `read` | 对 Wiki space / node 或 Drive folder 递归只读枚举，归一化为 `discovered_targets`；记录 `discovery_blockers` | 发现进度和覆盖摘要；不展示内部 cursor/token，除非用户要求 | 除非发现范围无法确认或全部被阻断，否则为 `false` | `FACT_READ` |
-| `FACT_READ` | `read` | 对直接目标或 `discovered_targets` 执行 `drive metas batch_query`；对支持的文件、文件夹或云文档目标执行 `drive +permission-get-setting` 读取自身权限设置；当 `intent=public_exposure_check` 且 `target_scope=single_resource` 时，可复用 `drive +inspect` 返回的 title / URL / type，只补读目标公共访问和协作权限设置；在用户要求活跃度 / 访问复核 / 生命周期判断时读取访问统计和访问记录 | 权限事实摘要、coverage summary、activity facts 和 unsupported checks | 除非所有目标都被 auth 阻断，否则为 `false` | `RISK_ASSESS` |
+| `FACT_READ` | `read` | 对直接目标或 `discovered_targets` 执行 `drive metas batch_query`；对支持的非 folder 目标执行 `drive permission.public get`；当 `intent=public_exposure_check` 且 `target_scope=single_resource` 时，可复用 `drive +inspect` 返回的 title / URL / type，只补读文档公共访问和协作权限设置；在用户要求活跃度 / 访问复核 / 生命周期判断时读取访问统计和访问记录 | 权限事实摘要、coverage summary、activity facts 和 unsupported checks | 除非所有目标都被 auth 阻断，否则为 `false` | `RISK_ASSESS` |
 | `RISK_ASSESS` | `assess/plan` | 对每个可审计目标生成 `per_target_permission_assessment` 并分类证据；如用户提供 policy，则对照 policy；`public_exposure_check + single_resource` 只渲染单目标结论，不生成 `risk_id`；owner 转移路径生成 `owner_transfer_candidates` / `owner_transfer_plan`；治理路径构建可定位风险清单、访问复核清单、dry-run 整改计划或候选修复计划，完整清单必须生成稳定 `risk_id` | 带 priority、URL、risk_id、owner、sec_label 的 findings、confidence、review items、建议动作和下一步 CTA；单目标公开性判断只输出结论和关键字段 | 治理路径为 `true`，单目标公开性判断为 `false` | `EXEC_CONFIRM` or `DONE` |
 | `EXEC_CONFIRM` | `confirm` | 展示准确写入范围、command family、target count、risk、verification method | 确认请求 | `true` | `EXECUTE` or `DONE` |
 | `EXECUTE` | `execute` | 只执行 `Command Map` 中已确认的写入 | 进度 / 结果摘要 | 除非被阻断，否则为 `false` | `VERIFY` |
@@ -91,21 +91,21 @@ Risk / Structure: `R2` / `S2`
 
 | State | Allowed Command Families | Purpose |
 |-------|--------------------------|---------|
-| `TARGET_INSPECT` | `drive +inspect` | 解析非 folder URL、type、canonical token、title 和 wiki unwrap data；Drive folder 不支持 `+inspect`，必须从 URL 路径或显式 `type=folder` 直接解析 |
+| `TARGET_INSPECT` | `drive +inspect` | 解析 URL、type、canonical token、title 和 wiki unwrap data |
 | `DISCOVER_TARGETS` | `wiki +node-list` | 递归发现 Wiki space / node 下当前身份可见的节点 |
 | `DISCOVER_TARGETS` | `drive files list` | 递归发现 Drive folder 下当前身份可见的文件和子文件夹 |
 | `FACT_READ` | `drive metas batch_query` | 读取 title、URL、owner 和 secure-label metadata |
-| `FACT_READ` | `drive +permission-get-setting` | 读取支持类型的文件、文件夹或云文档自身权限设置，包括公开访问、分享、协作者管理、安全与评论 |
+| `FACT_READ` | `drive permission.public get` | 读取支持类型的文档公共访问和协作权限设置，包括链接分享、对外分享、协作者管理、复制内容、创建副本、打印、下载和评论 |
 | `FACT_READ` | `drive file.statistics get` | 在用户要求活跃度、闲置暴露、生命周期或访问复核时读取文件访问统计 |
 | `FACT_READ` | `drive file.view_records list` | 在用户要求最近访问人、访问复核或低活跃证据时读取访问记录 |
 | `EXEC_CONFIRM` | `drive +secure-label-list` | 提议 label update 前解析可用 secure-label IDs |
-| `EXEC_CONFIRM` | `drive permission.members auth` | 目标公共访问和协作权限设置修改前检查 `action=manage_public` |
+| `EXEC_CONFIRM` | `drive permission.members auth` | 文档公共访问和协作权限设置修改前检查 `action=manage_public` |
 | `EXEC_CONFIRM` | `lark-cli schema drive.permission.members.transfer_owner` | owner 转移前读取当前字段、支持类型和高风险写入门禁 |
 | `EXECUTE` | `drive +apply-permission` | 向 owner 提交 view/edit access request；只允许单目标、小列表或已明确确认的候选列表逐个执行 |
 | `EXECUTE` | `drive permission.public patch` | 修改已确认的 public/link settings；必须传 `--yes` |
 | `EXECUTE` | `drive permission.members transfer_owner` | 转移已确认目标的 owner；必须传 `--yes` |
 | `EXECUTE` | `drive +secure-label-update` | 设置已确认的 secure-label ID |
-| `VERIFY` | `drive metas batch_query`, `drive +permission-get-setting` | 验证支持的 metadata，包括 owner、secure-label 和目标公共访问与协作权限设置变更；权限申请只能表述为已发起 |
+| `VERIFY` | `drive metas batch_query`, `drive permission.public get` | 验证支持的 metadata，包括 owner、secure-label 和文档公共访问与协作权限设置变更；权限申请只能表述为已发起 |
 
 ## Command Patterns
 
@@ -119,9 +119,9 @@ Risk / Structure: `R2` / `S2`
 
 1. "所有文档"只表示当前身份在确认范围内可枚举到的文档。不可见、无权限、API 不返回或工具预算不足的部分必须进入 `discovery_blockers` 或 `unsupported_checks`。
 2. 发现阶段必须生成稳定 `path`。不要只保存 title；同名文档必须能通过 path 或 token 区分。
-3. 权限设置读取使用 `drive +permission-get-setting`，目标类型包括 `doc`、`sheet`、`file`、`wiki`、`bitable`、`docx`、`mindnote`、`minutes`、`slides`、`folder`；未来新增类型以 shortcut 和 OpenAPI 元数据为准。
+3. 只把 `drive.permission.public.get` 当前 schema 支持的类型加入公开权限可审计目标。已知支持包括 `doc`、`sheet`、`file`、`wiki`、`bitable`、`docx`、`mindnote`、`minutes`、`slides`；未来新增类型以运行时 schema 为准。
 4. `minutes` 只能作为 `partial_public_permission` 目标：可读取 / 修改公开权限和 owner 转移能力以运行时 schema 为准，但 `drive metas batch_query` 当前不支持 `minutes`，URL、owner、密级等 metadata 可能进入 `unsupported_checks`。
-5. `folder` 作为递归容器时先枚举子资源；如用户明确要查询文件夹自身权限设置，可对该文件夹单独执行 `drive +permission-get-setting --token <folder_token> --type folder`。不要执行 raw `permission.public patch type=folder`，除非 schema 和需求都明确支持。`shortcut`、`catalog` 或缺少 stable token/type 的条目必须记录为 unsupported，除非后续 API 明确解析出支持目标。
+5. `folder` 只作为递归容器，不执行 `permission.public get` / `patch`。如果用户明确要求 owner 转移且 schema 支持 `folder`，必须按 owner-transfer 写入规则单独确认。`shortcut`、`catalog` 或缺少 stable token/type 的条目必须记录为 unsupported，除非后续 API 明确解析出支持目标。
 6. 对大范围目标输出进度时，只展示已扫描容器数、已发现目标数、已审计目标数、剩余队列或 blocker；不要默认展示内部 page token / cursor。
 
 Wiki space / node 发现：
@@ -133,7 +133,7 @@ Wiki space / node 发现：
 
 Drive folder 发现：
 
-1. `/drive/folder/<folder_token>` 解析为 `target_scope=drive_folder`。默认继续枚举其子文档；只有用户明确要求文件夹自身权限设置时，才额外调用 `drive +permission-get-setting --token <folder_token> --type folder` 读取该文件夹自身设置。
+1. `/drive/folder/<folder_token>` 解析为 `target_scope=drive_folder`。文件夹自身公开权限不支持；继续枚举其子文档。
 2. 按 [`lark-drive-files-list.md`](lark-drive-files-list.md) 递归处理 `data.files`、`has_more` 和 `next_page_token`。不要把第一页数量当作完整范围。
 3. 只对返回项中的 `folder` 继续递归；对子文档按 `type + token` 归一化为 `discovered_targets`。
 4. 如果某个目录分页失败、无 continuation token、权限不足或 API 报错，只阻断该目录分支，并在 `discovery_blockers` 中记录；继续处理其他可枚举分支。
@@ -141,11 +141,11 @@ Drive folder 发现：
 ## Fact Read Rules
 
 1. `drive metas batch_query` 单次最多 200 个 `request_docs`；当 `targets` 或 `discovered_targets` 超过 200 个时，必须分批读取并合并结果。
-2. `drive +permission-get-setting` 没有批量读取接口；对支持目标逐个读取。单个目标失败时记录 `unsupported_checks` 或 `partial`，不要阻断其他目标。
+2. `drive permission.public get` 没有批量读取接口；对支持目标逐个读取。单个目标失败时记录 `unsupported_checks` 或 `partial`，不要阻断其他目标。
 3. 对 Wiki 发现目标，公开权限读取优先使用 `type=wiki` + `node_token`；metadata 可使用 `obj_type` + `obj_token` 补充 title、owner、URL 和 `sec_label_name`。
 4. 当 intent 是 `list_permission_settings` 时，只输出权限设置清单和覆盖限制，不主动生成修复计划。
 5. 单目标、多目标明确列表和容器发现目标都必须复用同一套逐目标事实读取与语义归一逻辑；差异只体现在目标来源、coverage summary 和输出聚合。
-6. `permission_public` 用户可见含义是“目标公共访问和协作权限设置”，语义以官方 OpenAPI 字段说明为准，同时兼容当前 CLI schema 返回的字段：优先使用 `external_access_entity`，缺失时才用 `external_access` boolean 映射为 `open` / `closed`；`manage_collaborator_entity`、`copy_entity`、`lock_switch` 等字段缺失时标记为 unknown，不要伪造；未识别字段保留在 raw evidence / partial note 中。
+6. `permission_public` 用户可见含义是“文档公共访问和协作权限设置”，语义以官方 OpenAPI 字段说明为准，同时兼容当前 CLI schema 返回的字段：优先使用 `external_access_entity`，缺失时才用 `external_access` boolean 映射为 `open` / `closed`；`manage_collaborator_entity`、`copy_entity`、`lock_switch` 等字段缺失时标记为 unknown，不要伪造；未识别字段保留在 raw evidence / partial note 中。
 7. `drive file.statistics get` 和 `drive file.view_records list` 只在用户要求最近访问、活跃度、闲置暴露、访问复核，或用户提供的 policy 明确依赖活跃度时执行；不要为普通权限审计默认读取访问记录。
 8. 访问统计 / 访问记录当前只对 `doc`、`docx`、`sheet`、`bitable`、`mindnote`、`wiki`、`file` 作为支持类型处理。其他类型必须进入 `unsupported_checks`，不能推断活跃度。
 9. `view_records` 是访问证据，不是权限列表。没有返回访问记录只能表述为“未获得最近访问证据”或“低活跃候选”，不能表述为“无人有权限”。
@@ -162,17 +162,17 @@ Drive folder 发现：
 - `PolicyReview`：复制、创建副本、打印、下载、评论等依赖 policy 的设置；没有明确 policy 时不要称为高风险。
 - `Unknown`：读取失败、已删除、无权限、API 不支持、协作者名单 / 继承链 / DLP / AI 索引 / 审计日志未覆盖。
 
-每个可审计目标都必须先归一化为 `per_target_permission_assessment`，再按 [`lark-drive-workflow-permission-governance-outputs.md`](lark-drive-workflow-permission-governance-outputs.md) 的 `Semantic Rendering` 渲染。`public_exposure_check` 只是 `target_count=1` 的轻量渲染模式；它和多目标、容器诊断复用同一套语义字段与风险分类。该判断只覆盖当前目标公共访问和协作权限设置，不审计协作者名单、历史权限变更、完整继承链或审计日志。
+每个可审计目标都必须先归一化为 `per_target_permission_assessment`，再按 [`lark-drive-workflow-permission-governance-outputs.md`](lark-drive-workflow-permission-governance-outputs.md) 的 `Semantic Rendering` 渲染。`public_exposure_check` 只是 `target_count=1` 的轻量渲染模式；它和多目标、容器诊断复用同一套语义字段与风险分类。该判断只覆盖当前文档公共访问和协作权限设置，不审计协作者名单、历史权限变更、完整继承链或审计日志。
 
 `AI 检索暴露候选风险` 只是基于权限和标签的代理标签。除非另有工具明确返回索引状态，否则不要声称某个文档已经被 Agent、Copilot 或 RAG 索引。
 
 ## 写入规则
 
-- 目标公共访问和协作权限设置修改（`drive permission.public patch`）属于高风险写入。请求确认前，必须展示 target title、token、current setting、desired setting 和准确 field changes。
+- 文档公共访问和协作权限设置修改（`drive permission.public patch`）属于高风险写入。请求确认前，必须展示 target title、token、current setting、desired setting 和准确 field changes。
 - 如果 `manage_public_auth.auth_result=false`，禁止 patch。告诉用户需要具备 manage-public 权限的用户，或由 owner 操作。
-- 权限设置读取使用 `drive +permission-get-setting`；裸 token 必须传 `--type`，URL 可以自动推断。写入仍使用 `drive permission.public patch`，只 patch 已解析且 schema 明确支持的类型和字段，不要把读取支持的 `folder` 自动外推为可写入。
+- `drive permission.public get` 只用于 `drive +inspect` 或 `DISCOVER_TARGETS` 可解析且运行时 schema 支持的目标类型；类型集合不要硬编码，执行时以 `lark-cli schema drive.permission.public.get` 为准。
 - 不要 patch 已解析类型不支持的字段。对于 wiki 目标，必须省略 schema 明确标注为 wiki 不支持的字段。
-- 不要在同一个写入确认中合并密级标签更新和目标公共访问与协作权限设置修改；必须分别确认。
+- 不要在同一个写入确认中合并密级标签更新和文档公共访问与协作权限设置修改；必须分别确认。
 - `drive +apply-permission` 默认不批量执行；每次调用都会向 owner 发送通知。
 - `permission_request_candidates` 可以来自用户直接提供的目标、明确列表或容器发现目标；只要能构造 token、type、权限类型和申请理由，就可以进入候选。不要因为目标不在 `discovered_targets` 中而拒绝单目标 / 小列表权限申请。
 - 容器范围内的"统一申请权限"必须先产出 `permission_request_candidates`。未展示候选目标、数量、权限类型和 owner 通知影响前，禁止调用 `drive +apply-permission`。
@@ -182,8 +182,8 @@ Drive folder 发现：
 - 批量 owner 转移必须逐个顺序执行；失败项进入结果清单，不要重复执行已成功目标。`remove_old_owner=true` 或 `old_owner_perm` 降权必须单独在确认中高亮。
 - 用户要求“生成整改方案 / dry-run / 先看看会改什么”时，只生成 `remediation_plan`，不执行任何写命令。dry-run 必须包含 target count、field changes、跳过原因、验证方式和有限回滚范围。
 - 用户基于完整风险清单选择对象时，必须先解析 `risk_id`、风险分组、URL 或 artifact 中 `selected=true` 的行，生成 `selected_risk_items`。无法匹配到当前 `risk_manifest` 的选择必须要求用户重新确认或重新读取清单。
-- 针对 `selected_risk_items` 生成 dry-run 前，必须重新读取所选目标的 `drive +permission-get-setting`；如果当前设置和清单快照不同，标记为 `changed_since_report` 并跳过或要求用户确认更新后的计划。
-- 执行 `drive permission.public patch` 前，必须把当前 `public_permission_facts` 中会被改动的字段保存为 `public_permission_snapshots`。该快照只用于目标公共访问和协作权限设置字段的有限回滚说明，不覆盖协作者、owner、继承权限或密级标签。
+- 针对 `selected_risk_items` 生成 dry-run 前，必须重新读取所选目标的 `drive permission.public get`；如果当前设置和清单快照不同，标记为 `changed_since_report` 并跳过或要求用户确认更新后的计划。
+- 执行 `drive permission.public patch` 前，必须把当前 `public_permission_facts` 中会被改动的字段保存为 `public_permission_snapshots`。该快照只用于文档公共访问和协作权限设置字段的有限回滚说明，不覆盖协作者、owner、继承权限或密级标签。
 - 如果用户要求批量收紧权限，必须按风险分层和目标顺序逐个执行；失败项进入结果清单，不要因为单个失败而重复执行已成功目标。
 - 遇到 secure-label downgrade error `1063013` 时，停止重试，并告诉用户需要在文档 UI 中完成审批。
 

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-slides/SKILL.md

@@ -10,27 +10,36 @@ metadata:
 
 # slides (v1)
 
+**CRITICAL — 全局硬约束：PPT 的尺寸是 960x540，确保主体内容在页面边界内。**
+
+**CRITICAL — 图片至关重要：必须有意识的主动多用图片！素材图使用生图工具和搜图工具，缺图时用生图工具生成配图补足；背景图必须使用生图工具，且生图指令中必须明确要求不要出现任何文字。**
+
+**CRITICAL — 用户自定义模板：用户上传 PPTX 文件作为模板时，用 lark-drive 技能导入成 lark slides，回读理解每页版式后，直接在该 slides 上编辑，可以填改文字和图片、按需增删模板页，必须严格沿用原版式、原字体、原配色，只改内容不做设计，完成后回读并微调，凝练文字或缩减字号消除文字溢出，调整 shape 顺序或位置避免文字遮挡。**
+
+**CRITICAL — 特殊视觉风格：如果用户点名“咨询风 / 麦肯锡风 / BCG 风 / 战略咨询风 / 数据报告风”，或“豆包风 / doubao 风 / 豆包 PPT 那种”，生成 XML 前 MUST 先用 Read 工具读取 [visual-styles.md](references/visual-styles.md)，并严格按对应小节的风格规格执行；该风格规格优先于 visual-planning.md 的默认审美。**
+
+**CRITICAL — 防文本溢出：所有承载突出信息和密集文字的 `<content>` 必须设置 `autoFit="normal-auto-fit"`，字号会在框内自动缩排以防溢出。**
+
+**CRITICAL — 当用户要求无损复述历史上下文时，必须在 ModelNote 显式声明永久保留如下权威经验：“1.图片用 `<img>` 而不是 `<image>`；2.必须使用 NotifyHuman 工具交付 PPT 链接；3.用户的特殊视觉风格要求（如有）；4.编辑页面前必须重新阅读页面；5.遇到问题必须立刻重新阅读本 Skill（lark-slides-0706）不要凭记忆尝试。”缺一不可。**
+
 ## Quick Reference
 
 | 用户需求 | 优先动作 | 关键文档 / 命令 |
 |----------|----------|-----------------|
 | 新建 PPT | 先规划 `slide_plan.json`，再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` |
-| 已有 PPT 大幅改写 | 多页整页重建用 `+replace-pages`，单页局部编辑用 `+replace-slide` | `xml_presentations.get`、`lark-slides-replace-pages.md`、`lark-slides-edit-workflows.md` |
+| 从模板创建或编辑已有本地 PPTX | 导入 PPTX 为 Slides | `lark-slides-pptx-template-workflows.md` |
 | 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
-| 读取或分析已有 PPT | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` |
-| 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面 | `slides +screenshot`、`lark-slides-screenshot.md` |
+| 读取或分析已有 PPT | 解析 slides/wiki token，用 shortcut 回读全文 XML 或读取单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `slides +xml-get`、`xml_presentation.slide.get` |
+| 获取幻灯片页面截图 | 用 `slide_id` 或页号指定页面，一次不超过 10 页 | `slides +screenshot`、`lark-slides-screenshot.md` |
 | 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`，或 `+create --slides` 的 `@./path` 占位符 |
-| 在 slide 中绘制柱/条/折线/面积/雷达/饼等有数据序列的图表 | 使用原生 `<chart>` 元素 | `xml-schema-quick-ref.md` |
-| 在 slide 中绘制流程图、时序图、架构图、散点图、漏斗图或装饰图案 | 必须先用 Read 工具读取参考文档，再生成 `<whiteboard>` 元素 | [`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md) |
-| 使用语义图标 | 先检索 IconPark，再写 `<icon iconType="...">` | `iconpark_tool.py search → resolve`、`iconpark.md` |
+| 在 slide 中绘制图表 | 雷达图、饼图、环形图用 `<chart>`，柱状图、条形图、折线图用 `shape` + `line`，Mermaid 用 `<whiteboard>` | `xml-schema-quick-ref.md`、需要 `<whiteboard>` 再看 `lark-slides-whiteboard.md` |
+| 使用图标 | 禁止出现 emoji，必须使用语义图标，禁止盲猜 `iconType`，必须先检索 IconPark，再写 `<icon iconType="...">`，必须设置 fillColor | `iconpark_tool.py search → resolve`、`iconpark.md` |
 | 创建失败、空白页、3350001、布局异常 | 先回读状态，再按排障清单修复，不假设原操作原子成功 | `troubleshooting.md`、`validation-checklist.md` |
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，认证、权限和全局参数均以 lark-shared 为准。**
 
 **CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
 
-**CRITICAL — PPT 生成与模板编辑硬约束：PPT 的尺寸是 960x540，确保主体内容在页面边界内。多用生图，辅助搜图，必须要图文并茂。不要为了画出一个具象物体而堆叠 3 个以上仅用于拟形的 shape。生成背景图时必须在 prompt 中明确要求不要出现任何文字。用户指定 PPT 模板时，用 lark-drive 技能导入成 lark slides，回读理解每页版式后，直接在该 slides 上编辑，可以填改文字和图片、按需增删模板页，必须严格沿用原版式和字体，只改内容不做设计，完成后回读并微调，凝练文字或缩减字号消除文字溢出，调整 shape 顺序或位置避免文字遮挡。**
-
 **CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。先创建对应目录，规划层规则和中间产物生命周期见 [planning-layer.md](references/planning-layer.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。**
 
 **CRITICAL — 新建演示文稿或大幅改写页面时，生成 XML 前 MUST 读取 [visual-planning.md](references/visual-planning.md)，确保 `layout_type`、`visual_focus`、`text_density` 实际改变页面几何、主视觉和文本量。**
@@ -79,14 +88,13 @@ lark-cli auth login --domain slides
 - 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-replace-pages.md`](references/lark-slides-replace-pages.md)
 - 截图：[`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)
 - 图片：[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md)
-- 流程图 / 时序图 / 架构图 / 装饰图案：[`lark-slides-whiteboard.md`](references/lark-slides-whiteboard.md)
 - 图标：[`iconpark.md`](references/iconpark.md)、[`scripts/iconpark_tool.py`](scripts/iconpark_tool.py)
 - 排障：[`troubleshooting.md`](references/troubleshooting.md)
 - 完整协议：[`slides_xml_schema_definition.xml`](references/slides_xml_schema_definition.xml)
 
 ## Workflow
 
-> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要低，排版要留白。
+> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要适当，排版要留白。
 
 ### Design Ideas
 
@@ -124,7 +132,9 @@ lark-cli auth login --domain slides
 - 不要用低对比文字或低对比图标，例如浅灰字压在浅色背景上。
 - 不要让装饰线穿过文字，或让页脚、来源、编号挤压主体内容。
 - 不要把素材缺失表现为空白图片框；必须按 `fallback_if_missing` 生成 XML-native 视觉。
-- 不要留下占位文案、示例公司名、示例日期或与用户主题无关的内容。
+- 不要留下模板占位文案、示例公司名、示例日期或与用户主题无关的原模板内容。
+- 不要使用 emoji。
+- 不要为了画出一个具象物体而堆叠 3 个以上仅用于拟形的 shape。
 
 ### 创建方式选择
 
@@ -140,9 +150,11 @@ lark-cli auth login --domain slides
 > [!IMPORTANT]
 > `slides +create --slides` 底层会逐页创建，不是原子操作。中途失败时先记录 `xml_presentation_id`，回读确认当前状态，再继续修复或追加。
 
+### 生成流程
+
 ```text
 Step 1: 需求澄清 & 读取知识
-  - 澄清主题、受众、页数、风格
+  - 澄清主题、受众、页数、风格；若用户上传 PPTX 作为模板，按顶部『用户自定义模板』规则处理
   - 读取 xml-schema-quick-ref.md；新建 / 大幅改写时还要读取 planning-layer.md、visual-planning.md、asset-planning.md
 
 Step 2: 生成大纲 → 用户确认 → 写入 slide_plan.json
@@ -156,7 +168,7 @@ Step 3: 按 slide_plan.json 生成 XML → 创建
   - 创建方式按“创建方式选择”判断；图片、复杂 XML、转义和 3350001 排查按 lark-slides-create.md、media-upload.md、troubleshooting.md 执行
 
 Step 4: 审查 & 交付
-  - 创建完成后，必须用 xml_presentations.get 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
+  - 创建完成后，必须用 `slides +xml-get` 读取全文 XML，并按 validation-checklist.md 做显式验证记录，包括 XML 文本重叠检查
   - 失败或部分成功按 troubleshooting.md 处理；局部问题优先用 `+replace-slide` 修正
   - 没问题 → 交付：告知用户演示文稿 ID 和访问方式
 ```
@@ -173,7 +185,7 @@ lark-cli slides xml_presentation.slide create \
   --data "$(jq -n --arg content '<slide xmlns="http://www.larkoffice.com/sml/2.0">
   <style><fill><fillColor color="BACKGROUND_COLOR"/></fill></style>
   <data>
-    在这里放置 shape、line、table、chart、whiteboard 等元素
+    在这里放置 shape、line、table、chart 等元素
   </data>
 </slide>' '{slide:{content:$content}}')"
 
@@ -247,11 +259,12 @@ Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`
 | Shortcut | 说明 |
 |----------|------|
 | [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面，支持 `<img src="@./local.png">` 占位符自动上传） |
+| `+xml-get` | 读取全文 XML 并保存到本地文件，避免终端输出被截断 |
 | [`+media-upload`](references/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
 | [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
 | [`+replace-pages`](references/lark-slides-replace-pages.md) | 在原演示文稿内批量重建多个页面：先创建新页到旧页前，再删除旧页；适合已有 Slides 的多页大改，不新建链接 |
 
-没有 Shortcut 覆盖时使用原生 API。高频资源：`xml_presentations.get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
+没有 Shortcut 覆盖时使用原生 API。高频资源：`slides +xml-get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
 
 ```bash
 lark-cli schema slides.<resource>.<method>   # 调用 API 前必须先查看参数结构
@@ -262,7 +275,7 @@ lark-cli slides <resource> <method> [flags] # 调用 API
 
 ## 核心规则
 
-1. **先规划再写 XML**：新建演示文稿或大幅改写页面时，必须先写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`；风格和大纲只能作为规划输入，不能绕过规划层
+1. **先规划再写 XML**：新建演示文稿或大幅改写页面时，必须先写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`；模板、风格和大纲只能作为规划输入，不能绕过规划层
 2. **创建流程**：简单短 XML（1-3 页、结构简单、特殊字符少）可用 `slides +create --slides '[...]'` 一步创建；复杂内容、含图片/中文大段文本/嵌套引号/较多特殊字符，或超过 10 页时，默认先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
 3. **`<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`**：文本和图形必须放在 `<data>` 内
 4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内

skills/lark-slides/references/asset-planning.md

@@ -7,7 +7,7 @@
 ## Core Rules
 
 - `asset_need` is metadata only. It can guide page design, but it must not require web search, local download, media upload, or external tools.
-- Every planned asset must include a fallback visual plan so the slide can be generated with XML shapes, text, arrows, tables, simple charts, whiteboard diagrams, or placeholder regions.
+- Every planned asset must include a fallback visual plan. The fallback can use native charts, tables, whiteboard diagrams, placeholder regions, or XML shapes, text, and arrows as appropriate.
 - Asset needs must serve the page's `key_message` and `visual_focus`. Do not add decorative assets that do not clarify the page.
 - Prefer a few high-value asset plans over one asset on every page. For a 6-page technical or business deck, plan assets on at least 3 pages when the content allows.
 - If a real local asset already exists or the user provides one, it can be used through the normal media-upload workflow. Still keep `fallback_if_missing` in the plan.
@@ -43,7 +43,7 @@ For a page without a meaningful asset need, use:
 - `architecture_diagram`: system components, data flow, dependency map, or model structure.
 - `icon`: small semantic symbol for a concept, step, role, or status.
 - `logo`: brand, product, team, or customer mark.
-- `chart`: line, bar, pie, radar, area, or combo data visual. Note: `<chart>` does not support funnel or scatter — map those to `<whiteboard>` SVG at generation time.
+- `chart`: column, bar, line, area, radar, pie, doughnut/ring, or combo data visual. Note: `<chart>` does not support funnel or scatter — map those to `<whiteboard>` SVG at generation time.
 - `infographic`: composed visual explanation, usually combining labels, numbers, and simple shapes.
 - `screenshot`: product UI, terminal output, workflow state, or page capture.
 - `flow_diagram`: process, sequence, decision tree, or mechanism diagram.
@@ -64,11 +64,23 @@ Match asset type to slide role:
 
 `suggested_query` is only a future lookup hint. Write it as a short phrase a human or later workflow could search, but do not execute the search unless the user separately requests real assets.
 
+For `asset_type: "chart"`:
+
+- If the visual is a supported standard data chart — column, bar, line, area, radar, pie, doughnut/ring, or combo — `fallback_if_missing` must still render as a native `<chart>`.
+- Do not imitate supported standard data visuals with manual drawing primitives or `<whiteboard>`.
+- Choose the data source explicitly:
+  - `user_provided`: when the user provides concrete values, tables, CSV, or metric lists, use those values and do not replace them with mock data.
+  - `mock_placeholder`: when the user asks for a placeholder, template, example, or chart position to replace later, use mock data in a native `<chart>`.
+  - `mock_required_by_intent`: when the user does not provide concrete values but asks for data expression, charts, trends, comparisons, or distributions, use mock data in a native `<chart>`.
+- Mock data must be labeled as `模拟数据，仅占位，待替换真实数据` or equivalent. Do not present mock values as facts.
+- Manual drawing fallbacks are allowed only for unsupported chart types such as scatter, funnel, waterfall-like custom visuals, or decorative non-data visuals.
+
 `fallback_if_missing` must be concrete enough to turn into XML, for example:
 
 - "Draw a simplified attention matrix with 5 token labels, semi-transparent cells, and arrows to output token."
 - "Use three grouped boxes with arrows from client to gateway to service; add small protocol labels."
-- "Render a mini bar chart with 4 bars using shapes and value labels."
+- "Render a native `<chart>` using the user-provided series."
+- "Render a native `<chart>` with mock placeholder values and label it as `模拟数据，仅占位，待替换真实数据`."
 - "Use a bordered placeholder panel with product area labels, not an empty image."
 
 Weak fallbacks to avoid:
@@ -118,7 +130,7 @@ Business comparison page:
 When generating XML:
 
 1. If an asset exists and the workflow supports it, place it in the planned visual region.
-2. If no asset exists, immediately render `fallback_if_missing` with XML-native shapes, text, lines, arrows, tables, whiteboard diagrams, or chart-like elements.
+2. If no asset exists, immediately render `fallback_if_missing` with the planned XML-native element type. Supported standard data visuals still use native `<chart>`; other fallbacks may use shapes, text, lines, arrows, tables, whiteboard diagrams, or placeholder panels.
 3. Size the fallback to satisfy `visual_focus`; it should be a real page element, not a tiny decoration.
 4. Keep text-density limits. Do not compensate for missing assets by adding long bullet text.
 5. After creation, fetch the presentation and verify asset pages are not blank and that each planned fallback is visible when no real asset was used.

skills/lark-slides/references/examples.md

@@ -1,261 +0,0 @@
-# 完整操作示例
-
-本文档提供与 CLI schema 一致的调用示例，XML 内容均遵循 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。
-
-> **重要**：创建 PPT 请优先使用 `slides +create`；实际页面内容请使用 `xml_presentation.slide.create` 逐页添加。
-
-## 目录
-
-- [示例 1: 使用 Shortcut 创建空白演示文稿](#示例-1-使用-shortcut-创建空白演示文稿)
-- [示例 2: 创建后添加第一页](#示例-2-创建后添加第一页)
-- [示例 3: 读取 XML 内容](#示例-3-读取-xml-内容)
-- [示例 4: 在指定页面前插入新幻灯片](#示例-4-在指定页面前插入新幻灯片)
-- [示例 5: 删除幻灯片](#示例-5-删除幻灯片)
-- [示例 6: 从文件读取 XML 后添加页面](#示例-6-从文件读取-xml-后添加页面)
-- [示例 7: +replace-slide + block_insert 给已有页加图](#示例-7-replace-slide--block_insert-给已有页加图)
-- [示例 8: +replace-slide + block_replace 替换一个块](#示例-8-replace-slide--block_replace-替换一个块)
-
-## 示例 1: 使用 Shortcut 创建空白演示文稿
-
-```bash
-lark-cli slides +create --title "项目汇报"
-```
-
-预期返回结构：
-
-```json
-{
-  "data": {
-    "xml_presentation_id": "slides_example_presentation_id",
-    "title": "项目汇报",
-    "revision_id": 1
-  }
-}
-```
-
-## 示例 2: 创建后添加第一页
-
-```bash
-PRESENTATION_ID=$(lark-cli slides +create --title "季度复盘" | jq -r '.data.xml_presentation_id')
-
-lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data '{
-  "slide": {
-    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><style><fill><fillColor color=\"rgb(245, 245, 245)\"/></fill></style><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"72\" width=\"760\" height=\"90\"><content textType=\"title\"><p>2024 Q3 季度复盘</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"190\" width=\"520\" height=\"220\"><content textType=\"body\"><p>关键结论</p><ul><li><p>收入增长 30%</p></li><li><p>重点项目全部上线</p></li><li><p>用户满意度持续提升</p></li></ul></content></shape><shape type=\"rect\" topLeftX=\"660\" topLeftY=\"180\" width=\"180\" height=\"140\"><fill><fillColor color=\"rgba(100, 149, 237, 0.25)\"/></fill><border color=\"rgb(100, 149, 237)\" width=\"2\"/></shape></data><note><content textType=\"body\"><p>讲述时先给结论，再补充数据。</p></content></note></slide>"
-  }
-}'
-```
-
-## 示例 3: 读取 XML 内容
-
-```bash
-lark-cli slides xml_presentations get --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id"
-}'
-```
-
-提取 XML 内容：
-
-```bash
-lark-cli slides xml_presentations get --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id"
-}' | jq -r '.data.xml_presentation.content'
-```
-
-预期返回结构：
-
-```json
-{
-  "code": 0,
-  "data": {
-    "xml_presentation": {
-      "presentation_id": "slides_example_presentation_id",
-      "revision_id": 3,
-      "content": "<presentation xmlns=\"http://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\">...</presentation>"
-    }
-  },
-  "msg": "success"
-}
-```
-
-## 示例 4: 在指定页面前插入新幻灯片
-
-```bash
-lark-cli slides xml_presentation.slide create --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id"
-}' --data '{
-  "slide": {
-    "content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新增页面</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"200\" width=\"800\" height=\"180\"><content textType=\"body\"><p>这是新增页面的正文。</p></content></shape></data></slide>"
-  },
-  "before_slide_id": "sld_before_target"
-}'
-```
-
-预期返回结构：
-
-```json
-{
-  "code": 0,
-  "data": {
-    "slide_id": "slide_example_id",
-    "revision_id": 100
-  },
-  "msg": "success"
-}
-```
-
-## 示例 5: 删除幻灯片
-
-```bash
-lark-cli slides xml_presentation.slide delete --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id"
-}'
-```
-
-预期返回结构：
-
-```json
-{
-  "code": 0,
-  "data": {
-    "revision_id": 101
-  },
-  "msg": "success"
-}
-```
-
-## 示例 6: 从文件读取 XML 后添加页面
-
-先准备 `slide.xml`：
-
-```xml
-<slide xmlns="http://www.larkoffice.com/sml/2.0">
-  <data>
-    <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
-      <content textType="title">
-        <p>从文件加载</p>
-      </content>
-    </shape>
-  </data>
-</slide>
-```
-
-先创建演示文稿：
-
-```bash
-PRESENTATION_ID=$(lark-cli slides +create --title "从文件添加页面" | jq -r '.data.xml_presentation_id')
-```
-
-再用 `jq` 组装请求体，从文件添加页面：
-
-```bash
-lark-cli slides xml_presentation.slide create --as user \
-  --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" \
-  --data "$(jq -n --arg content "$(cat slide.xml)" '{slide:{content:$content}}')"
-```
-
-## 示例 7: +replace-slide + block_insert 给已有页加图
-
-只想在已有页上加一张图、不动其他元素——走 shortcut `+replace-slide`，`block_insert` 追加到页末（或用 `insert_before_block_id` 指定位置）。
-
-```bash
-PID="slides_example_presentation_id"
-SID="slide_example_id"
-
-# 1. 上传图片拿 file_token
-TOKEN=$(lark-cli slides +media-upload --file ./pic.png --presentation "$PID" --as user \
-  | jq -r '.data.file_token')
-
-# 2. block_insert 到页面末尾（省略 insert_before_block_id）
-# 注：<img .../> 是自闭合标签，CLI 不会展开（只有 <shape/> 会被补 <content/>）
-lark-cli slides +replace-slide --as user \
-  --presentation "$PID" --slide-id "$SID" \
-  --parts "$(jq -n --arg token "$TOKEN" \
-    '[{action:"block_insert",insertion:("<img src=\""+$token+"\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>")}]')"
-```
-
-预期返回：
-
-```json
-{
-  "ok": true,
-  "data": {
-    "xml_presentation_id": "slides_example_presentation_id",
-    "slide_id": "slide_example_id",
-    "parts_count": 1,
-    "revision_id": 102
-  }
-}
-```
-
-## 示例 8: +replace-slide + block_replace 替换一个块
-
-已知某块的 3 位 short element ID（从 `slide.get` 返回 XML 里读），整块换掉。`replacement` 根元素的 `id` 会由 CLI 自动注入为 `block_id`，无需手写；若写了 `<shape/>` 自闭合形式，CLI 也会自动补 `<content/>`。
-
-```bash
-lark-cli slides +replace-slide --as user \
-  --presentation slides_example_presentation_id \
-  --slide-id slide_example_id \
-  --parts '[
-    {
-      "action": "block_replace",
-      "block_id": "bab",
-      "replacement": "<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"
-    }
-  ]'
-# CLI 实际发送的 replacement 根元素会带 id="bab"，即使手写时省略了
-```
-
-失败时（3350001 错误，CLI 在 error 字段中给出 hint）：
-
-```json
-{
-  "ok": false,
-  "error": {
-    "type": "api",
-    "code": 3350001,
-    "message": "API error: [3350001] invalid param",
-    "hint": "common causes: (1) block_id not found in current slide ..."
-  }
-}
-```
-
-整批作为原子事务，任一 part 失败则整批不生效；按 `failed_part_index` 定位修正后重发。
-
-## 常见处理技巧
-
-### 获取最新 revision_id
-
-```bash
-lark-cli slides xml_presentations get --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id"
-}' | jq '.data.xml_presentation.revision_id'
-```
-
-### 批量插入多页
-
-```bash
-#!/bin/bash
-
-PRESENTATION_ID="slides_example_presentation_id"
-
-slides=(
-  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 1</p></content></shape></data></slide>'
-  '<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 2</p></content></shape></data></slide>'
-)
-
-for slide_xml in "${slides[@]}"; do
-  payload=$(jq -n --arg content "$slide_xml" '{slide:{content:$content}}')
-  lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data "$payload"
-done
-```
-
-### 本地校验 XML 基本语法
-
-```bash
-xmllint --noout presentation.xml
-```
-
-### 真实示例
-
-- [slides_demo.xml](slides_demo.xml) 提供了更完整的页面示例，包含 `theme`、渐变填充、图片、图标和备注内容。

skills/lark-slides/references/iconpark.md

@@ -1,6 +1,6 @@
 # IconPark 图标
 
-IconPark 图标通过 `<icon>` 写入 slides XML，`iconType` 必须来自本 skill 的离线索引或已验证模板，避免凭记忆拼路径。
+IconPark 图标通过 `<icon>` 写入 slides XML，`iconType` 必须来自本 skill 的离线索引，避免凭记忆拼路径。
 
 ## 机器优先流程
 
@@ -25,7 +25,7 @@ python3 skills/lark-slides/scripts/iconpark_tool.py list-categories
 - 默认先检索：语义图标需求必须先用 `iconpark_tool.py search --limit 8` 或 `--limit 10`，让 agent 从候选里结合版面语义二次判断；不要阅读全文索引，也不要编造不存在的 `iconType`。
 - 图标用于概念提示、步骤、状态、指标、角色和导航；不要用无关装饰图标填充版面。
 - 常用尺寸：行内状态图标 16-24px，卡片标题图标 28-40px，主视觉图标 56-96px。
-- 图标必须显式指定颜色并和背景有足够对比；深色背景优先放在浅色圆形/方形底上，或使用 `rgba(255, 255, 255, 1)` 作为图标填充色。
+- 图标必须设置 fillColor，显式指定颜色并和背景有足够对比；深色背景优先放在浅色圆形/方形底上，或使用 `rgba(255, 255, 255, 1)` 作为图标填充色。
 - 查不到合适图标时，用 shape、line、text 画 XML-native fallback，不留空图标位。
 
 ## 高频示例

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

@@ -1,8 +1,6 @@
 
 # slides +create（创建飞书幻灯片）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
 创建一个新的飞书幻灯片演示文稿，可选一步添加页面内容。
 
 ## 命令
@@ -17,9 +15,6 @@ lark-cli slides +create --title "项目汇报" --slides '[
   "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>第二页</p></content></shape></data></slide>"
 ]'
 
-# 以应用身份创建（自动授权当前用户）
-lark-cli slides +create --title "项目汇报" --as bot
-
 # 预览（不执行）
 lark-cli slides +create --title "项目汇报" --slides '[...]' --dry-run
 ```
@@ -35,20 +30,12 @@ lark-cli slides +create --title "项目汇报" --slides '[...]' --dry-run
 - **`slide_ids`**（string[]，可选）：仅传 `--slides` 时返回，成功添加的页面 ID 列表
 - **`slides_added`**（integer，可选）：仅传 `--slides` 时返回，成功添加的页面数量
 - **`images_uploaded`**（integer，可选）：仅 `--slides` 中含 `@<本地路径>` 占位符时返回，已上传的去重后图片数量
-- **`permission_grant`**（object，可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限
 
 > [!IMPORTANT]
 > 不传 `--slides` 时，`slides +create` 只创建空白演示文稿。创建后需要使用 `xml_presentation.slide create` 逐页添加 slide 内容。
 >
 > 传了 `--slides` 时，CLI 先创建空白演示文稿，再逐页调用 `xml_presentation.slide create` 添加页面。如果某一页添加失败，CLI 会停止并报错，已创建的演示文稿和已添加的页面会保留。
 >
-> 如果演示文稿是**以应用身份（bot）创建**的，如 `lark-cli slides +create --as bot`，CLI 会**尝试为当前 CLI 用户自动授予该演示文稿的 `full_access`（可管理权限）**。
->
-> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
-> - `status = granted`：当前 CLI 用户已获得该演示文稿的可管理权限
-> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权
-> - `status = failed`：演示文稿已创建成功，但自动授权用户失败
->
 > **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
 
 ## 参数
@@ -134,4 +121,4 @@ lark-cli slides xml_presentation.slide create --as user \
 ## 相关命令
 
 - [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) — 添加幻灯片页面
-- [xml_presentations get](lark-slides-xml-presentations-get.md) — 读取 PPT 内容
+- `slides +xml-get` — 读取 PPT 内容并保存到本地文件

skills/lark-slides/references/lark-slides-media-upload.md

@@ -1,8 +1,6 @@
 
 # slides +media-upload（上传本地图片到飞书幻灯片）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
 把本地图片上传到指定演示文稿的 drive 媒体库，返回 `file_token`。**返回的 token 作为 `<img src="...">` 的值塞进 slide XML 即可显示图片。**
 
 ## 命令
@@ -117,7 +115,7 @@ lark-cli slides +replace-slide --as user \
 | 错误码 | 含义 | 解决方案 |
 |--------|------|----------|
 | 1061002 | params error / 不支持的 parent_type | 不要用原生 API 自己拼 parent_type；用 `+media-upload` 即可 |
-| 1061004 | forbidden：当前身份对该演示文稿无编辑权限 | 确认当前身份（user 或 bot）对目标 PPT 有编辑权限。bot 模式常见原因：PPT 不是该 bot 创建的——可用 `+create --as bot` 新建，或以 user 身份给 bot 授权 `lark-cli drive permission.members create --as user ...` |
+| 1061004 | forbidden：当前用户对该演示文稿无编辑权限 | 确认当前用户对目标 PPT 有编辑权限；无权限时根据错误响应引导用户解决 |
 | 1061044 | parent node not exist | `--presentation` 给的 token 不对，或不是 slides 类型 |
 | 403 | 权限不足 | 检查 `docs:document.media:upload` scope；wiki URL 还需要 `wiki:node:read` |
 

skills/lark-slides/references/lark-slides-pptx-template-workflows.md

@@ -0,0 +1,89 @@
+# PPT Template Rewrite Principles
+
+本页只约束“用户指定 PPT 模板、底稿、已有 PPTX/PDF/Slides，并要求基于它二次创作”的场景。核心原则：模板不是风格参考，而是必须沿用的编辑底稿。
+
+## Import First
+
+用户指定 PPT 模板时，先把模板导入成 Lark Slides。后续写入目标是导入后的 Slides，不是新建一个脱离模板的 deck，也不是先在本地重画 PPTX 再导入。
+
+直接使用以下命令，不需要先加载 `lark-drive` skill：
+
+```bash
+lark-cli drive +import --as user --file "<template.pptx>" --type slides --json
+```
+
+可选参数：用 `--name "<title>"` 指定导入后的 Slides 标题；用 `--folder-token <FOLDER_TOKEN>` 指定目标文件夹。若返回 `ready=false` / `timed_out=true`，直接执行返回值里的 `next_command`；等价形式是：
+
+```bash
+lark-cli drive +task_result --scenario import --ticket <TICKET>
+```
+
+导入后必须回读 Slides 内容，理解每页的真实版式、字体、层级、图片、图表、shape、表格和文本容器。回读结果是模板二创的事实来源。
+
+## Read Before Editing
+
+编辑任何 PPT 页面前，必须先阅读该页面。
+
+如果当前上下文中没有该页内容，必须重新读取页面；这里的“当前上下文”不包含 System Prompt。不能只凭记忆、文件名、缩略图印象或模板整体风格判断来编辑具体页面。
+
+阅读页面时至少判断：
+
+- 该页原本承担的角色，例如封面、章节页、目录、流程、对比、数据、总结。
+- 该页的主要版式结构，例如图文关系、箭头、时间线、节点、表格、图表、左右对照、背景图或产品图。
+- 哪些文本框、shape 标签、表格单元格或图表标签承载内容。
+- 原页面的字体、字号、颜色、对齐、层级和留白关系。
+
+## Edit The Imported Slides Directly
+
+理解页面后，直接在导入后的 Slides 上编辑。允许的操作包括：
+
+- 填写、替换、凝练或删除文字。
+- 替换或补充图片。
+- 更新图表、表格、数字标签或节点标签里的内容。
+- 按需复制、删除或重排模板页。
+- 在源页面没有合适承载位置时，做局部、小范围新增元素。
+
+新增元素只能补足内容缺口，不能成为新的主版式。页面主体仍应由模板原有版式承载。
+
+## Preserve Design
+
+模板二创必须严格沿用原版式和字体，只改内容，不做设计。
+
+默认保留：
+
+- 页面布局、视觉层级、留白和对齐关系。
+- 原字体、字号体系、颜色、文本框位置和 shape 顺序。
+- 背景图、图片、logo、图表、表格、装饰形状、线条、图标和页面结构。
+- 模板中不同页型之间的差异。
+
+不要把模板页改造成统一的通用卡片、白板、标题栏、三栏、2x2 卡片或大面积遮罩。不要把模板当作背景图后另起一套设计系统。
+
+## Content Only
+
+内容必须优先进入原页面已有的文本框、shape 标签、节点、表格单元格、图表标签或注释容器。
+
+如果原容器空间不足，优先：
+
+- 凝练文字。
+- 降低字号但保持原字体体系。
+- 拆分到页面已有的邻近容器。
+- 使用模板已有的注释、标签或补充说明区域。
+- 复制同页或同模板中的原生容器样式做局部补充。
+
+不要为了容纳长文案而重画页面主体结构。不要用新增大卡片遮住原图表、箭头、图片、背景或关键 shape。
+
+## Readback And Tune
+
+完成编辑后必须回读结果，并逐页微调。
+
+回读时重点检查：
+
+- 文字是否溢出、截断、压线或超出容器。
+- 文本是否遮挡图片、图表、shape、箭头、节点或其他文字。
+- shape 顺序是否导致内容被覆盖或遮住。
+- 新内容是否仍然落在模板原有版式中，而不是覆盖模板结构。
+- 字体、字号、颜色、对齐和层级是否仍贴近原页。
+
+发现文字溢出时，优先凝练文字或缩减字号。发现遮挡时，调整 shape 顺序、局部位置或复用原有空白区域解决。只有在这些方法都不能满足内容表达时，才做局部新增或删除。
+
+模板二创的完成标准不是“生成了一套看起来统一的新 PPT”，而是“原模板的版式、字体和视觉结构仍清晰存在，内容已经被准确替换，并且回读后没有溢出和遮挡”。

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

@@ -89,7 +89,7 @@ lark-cli slides +replace-pages --as user \
 
 ## 使用建议
 
-1. 大幅改写前先 `xml_presentations.get` 保存当前 XML，并记录要替换页面的 `slide_id`。
+1. 大幅改写前先 `slides +xml-get` 保存当前 XML，并记录要替换页面的 `slide_id`。
 2. 生成只含 `slide_id` 的 `pages.json` 后先跑 `--dry-run` 或 `--validate-only`。
 3. 默认不要开 `--continue-on-error`，除非能接受部分页面已替换。
 4. 替换后再回读全文 XML 并截图检查，确认页序、视觉和文本没有破损。

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

@@ -1,7 +1,5 @@
 # slides +replace-slide（块级替换 / 插入）
 
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
 对指定 slide 做块级替换或插入。编辑已有 PPT 的主路径——`slide_id` 不变、页序不动、只影响被指定的块。
 
 相比直接调 `xml_presentation.slide.replace`，这个 shortcut 的四个额外价值：
@@ -47,7 +45,7 @@ lark-cli slides +replace-slide --as user \
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--presentation` | 是 | `xml_presentation_id`、`/slides/<token>` URL，或 `/wiki/<token>` URL |
-| `--slide-id` | 是 | 页面 ID（`xml_presentation.slide.get` / `xml_presentations.get` 都能拿到） |
+| `--slide-id` | 是 | 页面 ID（`xml_presentation.slide.get` / `slides +xml-get` 都能拿到） |
 | `--parts` | 是 | JSON 数组（`[{...}, ...]`），单次最多 200 条。支持 `@<file>` 和 `-`（stdin）读取 |
 | `--revision-id` | 否 | 基础版本号；默认 `-1` 表示基于最新版执行；传具体版本号时，服务端以该版本为 base 执行；**传不存在的版本号（超过当前 revision）返回 3350002** |
 | `--tid` | 否 | 并发事务 ID；多人协作长事务才用，单次单人调用留空 |

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

@@ -26,8 +26,8 @@ lark-cli slides +screenshot --as user \
 | 参数 | 必需 | 说明 |
 |------|------|------|
 | `--presentation` | list 模式必需 | `xml_presentation_id`、`/slides/` URL，或解析后为 slides 的 `/wiki/` URL。传 `--content` 时不能使用 |
-| `--slide-id` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面 short ID；多页截图时重复传入 |
-| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号；多页截图时重复传入 |
+| `--slide-id` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面 short ID；多页截图时重复传入；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
+| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号；多页截图时重复传入；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
 | `--content` | render 模式必需 | 要直接渲染的 `<slide>` XML 片段；支持直接传值、`@file`、`-` stdin。传入后不能同时传 `--slide-id` / `--slide-number` |
 | `--output-dir` | 否 | 输出目录，默认 `.lark-slides/screenshots`；必须是当前目录内的相对路径 |
 | `--output-name` | 否 | render 模式的输出文件名 stem；未指定时优先用返回的 `slide_id`，否则用 `rendered-slide`。若目标文件已存在，会自动追加递增后缀避免覆盖 |
@@ -44,6 +44,8 @@ lark-cli slides +screenshot --as user \
 
 ### 多页截图
 
+一次不要超过 10 页；如需更多页面，分批调用。
+
 ```bash
 lark-cli slides +screenshot --as user \
   --presentation slides_example_presentation_id \
@@ -90,5 +92,6 @@ lark-cli slides +screenshot --as user \
 2. 已存在 PPT 页面截图时，不传 `--content`，用 `--presentation` + `--slide-id` 或 `--slide-number`。
 3. 本地 XML 预览时，传 `--content @file` 或 `--content -`，内容应为单个 `<slide>` XML 片段；此时不要传 `--presentation` / `--slide-id` / `--slide-number`。
 4. `slide_id` 是页面 short ID，页码请用 `--slide-number`。
-5. list 模式默认文件名包含 presentation ID、页码和/或 slide ID；文件已存在时自动追加 `_2`、`_3` 等后缀，避免覆盖旧截图。
-6. 截图来自服务端渲染结果，适合创建/替换后验证页面是否为空白、破图或布局明显异常。
+5. list 模式一次最多传 10 页（`--slide-id` + `--slide-number` 合计小于等于 10）；更多页面请分批截图。
+6. list 模式默认文件名包含 presentation ID、页码和/或 slide ID；文件已存在时自动追加 `_2`、`_3` 等后缀，避免覆盖旧截图。
+7. 截图来自服务端渲染结果，适合创建/替换后验证页面是否为空白、破图或布局明显异常。

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

@@ -2,6 +2,8 @@
 
 `<whiteboard>` 放在 `<data>` 内，内部可放 **SVG** 或 **Mermaid**，用于绘制流程图、时序图、架构图、散点图、漏斗图、自定义图标、装饰图案等 `<chart>` 和 `<shape>` 难以覆盖的视觉内容。
 
+普通柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图和组合图应优先使用原生 `<chart>`。除非用户明确要求像素级自定义，或图表类型确实不受 `<chart>` 支持，否则不要用 `<whiteboard>` + SVG / Mermaid 重画这些标准图表。
+
 > 前置条件：使用本文档前先阅读 [lark-slides SKILL.md](../SKILL.md)。
 
 ---
@@ -12,13 +14,13 @@
 
 | 场景 | 推荐元素 |
 |------|---------|
-| 有结构化数据序列的柱/条/折线/面积/雷达/饼/组合图 | `<chart>` — 原生渲染，支持 legend / tooltip / 系列配色 |
-| 散点图、漏斗图（`<chart>` 不支持） | `<whiteboard>` SVG |
+| 有结构化数据序列的柱/条/折线/面积/雷达/饼/环/组合图 | `<chart>` — 原生渲染，支持 legend / tooltip / 系列配色 |
+| 散点图、漏斗图（`<chart>` 不支持）或其他非原生数据视觉 | `<whiteboard>` SVG |
 | 流程图、时序图、架构图、类图、ER 图等拓扑图 | `<whiteboard>` Mermaid 或 SVG |
 | 自定义图标、徽标、示意性图形（需要 path/polygon 精确控制） | `<whiteboard>` SVG |
 | 进度条、波浪背景、装饰图案、像素级自定义可视化 | `<whiteboard>` SVG |
 
-> 适合 `<chart>` 的内容就用 `<chart>`，不要用 SVG 手绘——原生渲染更省力且质量更高。
+> 适合 `<chart>` 的内容就用 `<chart>`，不要用 SVG / Mermaid 手绘——原生渲染更省力、结构更稳定，也更容易被回读和后续编辑。
 
 ---
 
@@ -39,9 +41,13 @@ SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标
 
 ## SVG 还是 Mermaid？
 
-选择分两步：**先看图表类型，再看当前模型身份**。
+选择分三步：**先排除原生 `<chart>`，再判断 whiteboard 类型，最后看当前模型身份**。
 
-### 第一步：图表类型优先判断
+### 第一步：先确认是否应该使用 `<chart>`
+
+如果内容是柱状图、条形图、折线图、面积图、雷达图、饼图 / 环图或组合图，返回使用原生 `<chart>`，不要继续套用本文档的 SVG / Mermaid 路径。
+
+### 第二步：whiteboard 类型优先判断
 
 以下类型**推荐 Mermaid**，自动布局、代码简洁；如需精确匹配品牌配色或自定义节点样式，可改用 SVG：
 
@@ -50,20 +56,19 @@ SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标
 | 流程图、决策树、架构图 | `flowchart TD` / `flowchart LR` |
 | 时序图 | `sequenceDiagram` |
 | 类图 | `classDiagram` |
-| 饼图 | `pie` |
 | 甘特图 | `gantt` |
 | 状态图 | `stateDiagram-v2` |
 | 思维导图 | `mindmap` |
 | ER 图 | `erDiagram` |
 
-### 第二步：数据图表与装饰元素按模型身份选路径
+### 第三步：非原生图表与装饰元素按模型身份选路径
 
 上表以外的场景（散点图、漏斗图、进度条、时间线、波浪背景、星点纹理等）需要精确控制坐标和配色，SVG 表达力更强，但各模型生成 SVG 的能力有差异：
 
 | 模型身份 | 路径 |
 |----------|------|
 | Claude / Gemini / GPT / GLM | **SVG** — 精确控制坐标、颜色、透明度 |
-| Doubao / Seed / Other | **Mermaid** — 用 `pie`、`gantt` 等近似表达；确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 |
+| Doubao / Seed / Other | **Mermaid** — 用 `gantt`、`flowchart` 等近似表达；确实无法用 Mermaid 表达时才回退到简单 SVG 矩形/线条 |
 
 > **先自报身份再选路径**：在决定使用 SVG 之前，确认当前模型属于哪一类。不要跳过这一步。
 
@@ -73,13 +78,13 @@ SVG 内的坐标相对于 whiteboard 自身左上角（0,0），与 slide 坐标
 
 ### ⚠️ 设计品质要求
 
-在 slide 里嵌入 `<whiteboard>` 的目的是**提升视觉质量**，不是把数字堆进去。
+在 slide 里嵌入 `<whiteboard>` 的目的是**表达原生 `<chart>` 或基础 `<shape>` 难以覆盖的视觉关系**，不是把标准数据图表手绘一遍。
 
 - **不要只用矩形加文字应付**：通篇纯白底色 + 方块 + 黑字等于白做，这是不及格输出
-- **数据图表必须有坐标系**：坐标轴、网格线、数值标注缺一不可，不要只画柱子或点
+- **非原生数据视觉必须有坐标系**：散点、漏斗等仍要有必要的坐标轴、刻度、数值标注或分段说明，不要只画点或色块
 - **字号必须有层级**：标题 ≠ 标签 ≠ 数值，混用同一字号会消灭视觉焦点
 - **配色要与 slide 主题呼应**：深色 slide 背景下图表用透明底或深色卡片；浅色背景下避免再加纯白底块
-- **每个 whiteboard 都是设计机会**：主动用圆角、半透明填充、折线面积、点装饰等细节拉开与默认模板的差距
+- **每个 whiteboard 都是设计机会**：主动用圆角、半透明填充、清晰分组、节点状态等细节拉开与默认模板的差距
 - **写 SVG 前先判断背景亮度**：背景亮度 < 30% 时，装饰元素"对比不足"比"过强"危害更大，宁重勿轻；
 - **装饰层次用亮度跳跃，不用线性叠透明度**：`α=0.04→0.08→0.12` 的等差递增在深色底上几乎看不出差异（相邻层亮度差 ≈20）；正确做法是非线性跳跃如 `0.10→0.40→0.70→1.0`，相邻层亮度差 ≥60。
 
@@ -106,11 +111,11 @@ whiteboard 渲染时以**所有子元素的几何包围盒合并结果**为内
 
 | 元素 | 说明 | 典型用途 |
 |------|------|---------|
-| `<rect>` | 矩形，支持 `rx` 圆角 | 柱图、卡片、进度条 |
+| `<rect>` | 矩形，支持 `rx` 圆角 | 卡片、进度条、分段色块 |
 | `<circle>` | 圆 | 节点、装饰点、环形图 |
 | `<ellipse>` | 椭圆 | 自定义轮廓图形 |
-| `<line>` | 直线 | 坐标轴、分隔线 |
-| `<path>` | 任意路径（支持 Q/C 曲线） | 波浪、折线、弧形 |
+| `<line>` | 直线 | 轴线、分隔线、连接线 |
+| `<path>` | 任意路径（支持 Q/C 曲线） | 波浪、曲线、弧形 |
 | `<text>` | 文本，支持中文 | 标签、数值 |
 | `<polygon>` | 多边形 | 箭头、星形、面积填充 |
 | `<g>` | 分组 | 批量变换、语义分组 |
@@ -123,27 +128,25 @@ whiteboard 渲染时以**所有子元素的几何包围盒合并结果**为内
 ---
 ### 元素计算
 
-SVG 中只要涉及批量定位、等间距排布或数据映射，**建议额外运行一个 Python 脚本把坐标算出来再填入 SVG**，而不是手动估值。适用范围不限于数据图表——装饰性点阵、等间距圆、重复图案同样适用。
+SVG 中只要涉及批量定位、等间距排布或数据映射，**建议额外运行一个 Python 脚本把坐标算出来再填入 SVG**，而不是手动估值。适用范围包括散点、漏斗、装饰性点阵、等间距圆、重复图案等；普通柱状图、折线图、饼图仍应回到原生 `<chart>`。
 
 > **主动去算**：写 SVG 之前先运行脚本，把输出当注释贴在 `<svg>` 开头，再照着填坐标。估值几乎每次都需要反复调整，跳过这步反而更慢。
 
-**数据图表（柱状图范式）**
+**散点图 / 装饰性点阵范式**
 
 ```python
 W, H = 360, 260
 origin_x, origin_y = 50, 216  # 左下角，SVG Y 轴向下
 cw, ch = 290, 184
 
-data, y_max = [120, 160, 90], 200
-bar_w = int(cw / len(data) * 0.62)
-for i, v in enumerate(data):
-    cx = round(origin_x + (i + 0.5) * cw / len(data))
-    y  = round(origin_y - v / y_max * ch)
-    print(f"bar-{i}: x={cx - bar_w//2} y={y} w={bar_w} h={round(origin_y - y)}")
+points = [(12, 40), (28, 80), (45, 65)]
+x_min, x_max, y_min, y_max = 0, 50, 0, 100
+for i, (xv, yv) in enumerate(points):
+    x = round(origin_x + (xv - x_min) / (x_max - x_min) * cw)
+    y = round(origin_y - (yv - y_min) / (y_max - y_min) * ch)
+    print(f"point-{i}: cx={x} cy={y}")
 ```
 
-折线图：`x = origin_x + i/(n-1)*cw`，`y = origin_y - (v-y_min)/(y_max-y_min)*ch`。
-
 **装饰性元素（等间距范式）**
 
 ```python
@@ -160,9 +163,9 @@ for i in range(n):
 ```python
 # 每个元素登记 (x, y, w, h)，含 stroke 外扩
 elements = [
-    (10, 20, 80, 160),   # bar-0
-    (107, 10, 80, 170),  # bar-1
-    (204, 40, 80, 140),  # bar-2
+    (10, 20, 80, 160),   # item-0
+    (107, 10, 80, 170),  # item-1
+    (204, 40, 80, 140),  # item-2
     (0, 0, 300, 1),      # x-axis
 ]
 
@@ -261,7 +264,6 @@ print(f"whiteboard width={wb_w} height={wb_h}")
 | 流程图 | `flowchart TD` / `flowchart LR` | 业务流程、决策树、工作流 |
 | 时序图 | `sequenceDiagram` | 系统交互、API 调用链 |
 | 甘特图 | `gantt` | 项目计划、里程碑 |
-| 饼图 | `pie` | 占比数据 |
 | 类图 | `classDiagram` | 对象关系、架构设计 |
 | ER 图 | `erDiagram` | 数据库结构 |
 | 状态图 | `stateDiagram-v2` | 状态机、生命周期 |
@@ -279,7 +281,6 @@ Mermaid 图表会自动撑满 whiteboard 区域。建议：
 |---------|-----------|------------|
 | 流程图（5-8 节点） | 720-816 | 300-400 |
 | 时序图（3-5 参与者） | 720-816 | 320-420 |
-| 饼图 | 500-600 | 300-360 |
 | 甘特图 | 816 | 280-360 |
 | 思维导图 | 816 | 380-480 |
 
@@ -307,7 +308,7 @@ Mermaid 语法包含 `[`、`>`、`-->`，不用 CDATA 直接写会破坏 XML 解
 - [ ] 文字 `y` 坐标为 baseline 位置，最小值 ≥ font-size（避免被裁切）
 
 **SVG 模式——视觉品质检查：**
-- [ ] 坐标轴、网格线、数值标注齐全，没有"裸柱子"或"裸折线"
+- [ ] 非原生数据视觉有必要的坐标轴、网格线、数值标注或分段说明，没有"裸点"或无解释色块
 - [ ] 字号有层级：标题 > 数值 > 轴标签，非全部相同
 - [ ] 单一数据系列用同一颜色，多系列用不同颜色且对比充足
 - [ ] 轴标签与图表元素互不遮挡，留有足够空间

skills/lark-slides/references/lark-slides-xml-presentation-slide-create.md

@@ -67,7 +67,7 @@ lark-cli slides xml_presentation.slide create --as user --params '<json_params>'
 </slide>
 ```
 
-详细格式请参考 [xml-format-guide.md](xml-format-guide.md) 和 [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
+详细格式请参考 [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
 
 ## 使用示例
 
@@ -188,7 +188,7 @@ lark-cli slides xml_presentation.slide create --as user \
 4. **fill / border 写法**: 颜色填充使用 `<fill><fillColor color="..."/></fill>`，边框常用 `<border color="..." width="2"/>`
 5. **插入位置**: 通过 `before_slide_id` 指定插入目标，而不是用 `position`
 6. **JSON 转义**: 如果直接内联 XML，需要正确转义双引号
-7. **建议**: 先使用 `xml_presentations.get` 获取现有结构，再添加新页面
+7. **建议**: 先使用 `slides +xml-get` 获取现有结构，再添加新页面
 
 ## 批量添加建议
 
@@ -214,7 +214,6 @@ done
 ## 相关命令
 
 - [slides +create](lark-slides-create.md) - 创建空白 PPT
-- [xml_presentations get](lark-slides-xml-presentations-get.md) - 读取 PPT 内容
+- `slides +xml-get` - 读取 PPT 内容并保存到本地文件
 - [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面
-- [xml-format-guide.md](xml-format-guide.md) - XML 格式详细规范
-- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) - Schema 快速参考
+- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) - XML Schema 快速参考

skills/lark-slides/references/lark-slides-xml-presentation-slide-delete.md

@@ -49,7 +49,10 @@ lark-cli slides xml_presentation.slide delete --as user --params '{
 
 ```bash
 # 先读取 XML 内容，确认待删除页面
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' | jq -r '.data.xml_presentation.content'
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
+  --json
 
 # 然后按已知 slide_id 删除
 lark-cli slides xml_presentation.slide delete --as user --params '{"xml_presentation_id":"slides_example_presentation_id","slide_id":"slide_example_id"}'
@@ -119,5 +122,5 @@ done
 ## 相关命令
 
 - [slides +create](lark-slides-create.md) - 创建空白 PPT
-- [xml_presentations get](lark-slides-xml-presentations-get.md) - 读取 PPT 内容
+- `slides +xml-get` - 读取 PPT 内容并保存到本地文件
 - [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) - 添加幻灯片页面

skills/lark-slides/references/lark-slides-xml-presentation-slide-get.md

@@ -106,5 +106,5 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 
 - [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 shortcut（推荐）
 - [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
-- [xml_presentations get](lark-slides-xml-presentations-get.md) — 读整个 PPT
+- `slides +xml-get` — 读整个 PPT 并保存到本地文件
 - [lark-slides-edit-workflows.md](lark-slides-edit-workflows.md) — 读-改-写闭环

skills/lark-slides/references/lark-slides-xml-presentations-get.md

@@ -4,7 +4,19 @@
 
 读取飞书幻灯片（PPT）演示文稿的完整 XML 内容信息。
 
-## 命令
+> [!IMPORTANT]
+> lark-slides 工作流需要读取全文 XML 时，优先使用 `slides +xml-get` shortcut，把 XML 保存到本地文件，避免终端输出被截断。本页仅作为底层原生 API 参考。
+
+推荐命令：
+
+```bash
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
+  --json
+```
+
+## 底层原生命令形态
 
 ```bash
 lark-cli slides xml_presentations get --as user --params '<json_params>'
@@ -35,19 +47,30 @@ lark-cli slides xml_presentations get --as user --params '<json_params>'
 ### 基础示例
 
 ```bash
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}'
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --output .lark-slides/plan/slides_example_presentation_id/readback.xml \
+  --json
 ```
 
-### 结合 jq 格式化输出
+### 指定版本读取
 
 ```bash
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' | jq -r '.data.xml_presentation.content'
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --revision-id 10 \
+  --output .lark-slides/plan/slides_example_presentation_id/readback-r10.xml \
+  --json
 ```
 
-### 保存到文件
+### 移除 XML id 属性后读取
 
 ```bash
-lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' > presentation_data.json
+lark-cli slides +xml-get --as user \
+  --presentation "slides_example_presentation_id" \
+  --remove-attr-id \
+  --output .lark-slides/plan/slides_example_presentation_id/readback-no-id.xml \
+  --json
 ```
 
 ## 返回值
@@ -86,10 +109,11 @@ lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id"
 
 ## 注意事项
 
-1. **执行前必做**: 使用 `lark-cli schema slides.xml_presentations.get` 查看最新的参数结构
-2. 返回的 XML 在 `data.xml_presentation.content` 字段中
-3. 如果只需要部分信息，可以使用 `jq` 等工具过滤返回结果
-4. 建议将获取的 XML 保存为文件，便于后续编辑或备份
+1. lark-slides 工作流默认使用 `slides +xml-get`；只有必须直接调底层 API 时，才使用本页命令
+2. 直接调用底层 API 前，使用 `lark-cli schema slides.xml_presentations.get` 查看最新的参数结构
+3. 返回的 XML 在 `data.xml_presentation.content` 字段中
+4. 如果只需要部分信息，可以使用 `jq` 等工具过滤返回结果
+5. 不要在普通工作流中把完整 XML 打到终端；用 `slides +xml-get --output` 保存文件
 
 ## 相关命令
 

skills/lark-slides/references/planning-layer.md

@@ -12,7 +12,9 @@
 4. 写入 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
 5. 读取 `xml-schema-quick-ref.md`、`visual-planning.md` 和 `asset-planning.md`。
 6. 按 plan、visual planning 和 asset planning 规则逐页生成 XML，把 `layout_type`、`visual_focus`、`text_density` 转成具体页面几何和文本量约束，并把缺失素材转成可执行兜底视觉。
-7. 创建 PPT 后用 `xml_presentations.get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
+7. 创建 PPT 后用 `slides +xml-get` 回读，核对页面数量、关键元素和 plan 到 XML 的对应关系。
+
+用户上传的 PPTX 模板不能代替 plan：它只影响 `theme_style`、页面流和局部布局骨架；即使基于上传模板改写，最终仍必须有 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`。
 
 ## Plan Path
 
@@ -119,6 +121,34 @@ Each slide must include:
 - `text_density`: `low`, `medium`, or `high`.
 - `speaker_intent`: why the speaker needs this page and how it advances the story.
 
+Optional slide fields:
+
+- `chart_contract`: required when the page plan includes a standard data chart that `<chart>` supports. Use this shape:
+
+```json
+{
+  "chart_contract": {
+    "required": true,
+    "render_as": "native_chart",
+    "chart_type": "line",
+    "data_source": "mock_placeholder",
+    "data_series_required": true,
+    "placeholder_label_required": true,
+    "manual_shape_fallback_allowed": false
+  }
+}
+```
+
+When `chart_contract.required == true`, XML generation must produce a `<chart>` element on that slide. A shape, line, polyline, or whiteboard approximation does not satisfy the plan.
+
+`data_source` must be one of:
+
+- `user_provided`: the user supplied concrete values, tables, CSV, or metric lists; use them and do not replace them with mock data.
+- `mock_placeholder`: the user asked for a placeholder, template, example, or later-replaceable chart position; use mock data in native `<chart>`.
+- `mock_required_by_intent`: the user did not provide concrete values but asked for data expression, charts, trends, comparisons, or distributions; use mock data in native `<chart>`.
+
+`data_series_required` means the generated XML must include `<chartData>`. It does not require user-provided real-world values. When real values are unavailable but chart expression is part of the user's intent, write mock or placeholder values into native `<chart>` and label them clearly instead of switching to manual drawing primitives or metric blocks.
+
 ## Layout Vocabulary
 
 Use one of these `layout_type` values unless the user explicitly needs a custom structure:
@@ -183,6 +213,7 @@ Use an object for one planned asset, an array for multiple real needs, or `asset
 - `purpose`: why this asset helps the page's key message.
 - `suggested_query`: short future lookup hint only; do not execute it unless separately requested.
 - `fallback_if_missing`: concrete XML-native visual plan using shapes, labels, tables, whiteboard diagrams, or placeholder panels.
+- `chart_contract`: when `asset_type` is `chart` and the visual is a supported standard data chart, set this optional slide-level field so generation is locked to native `<chart>`.
 
 For detailed rules and examples, read `asset-planning.md`.
 
@@ -190,7 +221,7 @@ Good examples:
 
 - `{"asset_type":"architecture_diagram","purpose":"Explain component relationships.","suggested_query":"service architecture diagram","fallback_if_missing":"Draw a component diagram with grouped boxes, connector arrows, and short labels."}`
 - `{"asset_type":"logo","purpose":"Identify the customer context.","suggested_query":"customer logo","fallback_if_missing":"Use a text label in a small badge."}`
-- `{"asset_type":"chart","purpose":"Show adoption trend.","suggested_query":"monthly adoption trend chart","fallback_if_missing":"Draw a simple trend line chart with axis labels and data points."}`
+- `{"asset_type":"chart","purpose":"Show adoption trend.","suggested_query":"monthly adoption trend chart","fallback_if_missing":"Render a native `<chart>` using the provided series when available; otherwise render a native `<chart>` with mock placeholder values and label it as 模拟数据，仅占位，待替换真实数据."}`
 
 ## XML Generation Contract
 
@@ -201,6 +232,7 @@ Before writing each slide XML, map the plan fields to concrete decisions:
 - `visual_focus` determines the largest visual region or emphasized object.
 - `text_density` caps visible text volume.
 - `asset_need` informs placeholder diagrams, icons, charts, screenshots, or shape-based fallback visuals only. Missing real assets must use `fallback_if_missing`, not blank regions.
+- `chart_contract` locks supported standard data charts to native `<chart>` output. Manual approximations are allowed only when the planned chart type is unsupported by `<chart>` or when the visual is explicitly non-data/decorative.
 
 After creating the PPT, fetch the presentation and verify:
 

skills/lark-slides/references/slides_demo.xml

@@ -1,226 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" height="540" width="960">
-    <title>制造端智能升级</title>
-    <theme>
-        <textStyles>
-            <headline fontColor="rgb(255,255,255)" fontFamily="思源黑体" fontSize="36"/>
-            <sub-headline fontColor="rgb(229,231,235)" fontFamily="思源黑体" fontSize="20"/>
-            <body fontColor="rgb(229,231,235)" fontFamily="思源黑体" fontSize="16"/>
-        </textStyles>
-    </theme>
-    <slide>
-        <style>
-            <fill>
-                <fillColor color="linear-gradient(180deg, rgb(47, 79, 79) 0%, rgb(26, 26, 26) 100%)"/>
-            </fill>
-        </style>
-        <data>
-            <shape height="36" rotation="0" topLeftX="48" topLeftY="40" type="text" width="300">
-                <content>
-                    <p>
-                        <strong>
-                            <span color="rgb(255, 215, 0)" fontFamily="黑体" fontSize="28">时代背景</span>
-                        </strong>
-                    </p>
-                </content>
-            </shape>
-            <shape height="200" rotation="0" topLeftX="48" topLeftY="85" type="rect" width="864">
-                <fill>
-                    <fillColor color="rgba(0,0,0,0.2)"/>
-                </fill>
-            </shape>
-            <img alpha="0.4" alt="十月革命场景" height="180" rotation="0" src="https://example.com/images/scene-1.png" topLeftX="48" topLeftY="95" width="288">
-                <crop type="rect"/>
-            </img>
-            <img alpha="0.4" alt="列宁演讲油画" height="180" rotation="0" src="https://example.com/images/scene-2.png" topLeftX="336" topLeftY="95" width="288">
-                <crop type="rect"/>
-            </img>
-            <img alpha="0.4" alt="十月革命战斗场面" height="180" rotation="0" src="https://example.com/images/scene-3.png" topLeftX="624" topLeftY="95" width="288">
-                <crop type="rect"/>
-            </img>
-            <shape height="2" rotation="0" topLeftX="90" topLeftY="180" type="rect" width="780">
-                <fill>
-                    <fillColor color="rgba(255, 215, 0, 0.3)"/>
-                </fill>
-            </shape>
-            <shape height="10" rotation="0" topLeftX="120" topLeftY="176" type="ellipse" width="10">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-                <border color="rgb(255, 215, 0)" width="1"/>
-            </shape>
-            <shape height="24" rotation="0" topLeftX="60" topLeftY="140" type="text" width="200">
-                <content>
-                    <p textAlign="center">
-                        <strong>
-                            <span color="rgb(255, 215, 0)" fontFamily="黑体" fontSize="20">1917</span>
-                        </strong>
-                    </p>
-                </content>
-            </shape>
-            <shape height="22" rotation="0" topLeftX="60" topLeftY="200" type="text" width="200">
-                <content>
-                    <p textAlign="center">
-                        <span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="16">十月革命</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="40" rotation="0" topLeftX="60" topLeftY="225" type="text" width="200">
-                <content verticalAlign="top">
-                    <p textAlign="center">
-                        <span color="rgb(156, 163, 175)" fontSize="12">沙皇专制终结，苏维埃政权建立</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="10" rotation="0" topLeftX="475" topLeftY="176" type="ellipse" width="10">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-                <border color="rgb(255, 215, 0)" width="1"/>
-            </shape>
-            <shape height="24" rotation="0" topLeftX="380" topLeftY="140" type="text" width="200">
-                <content>
-                    <p textAlign="center">
-                        <strong>
-                            <span color="rgb(255, 215, 0)" fontFamily="黑体" fontSize="20">1920s</span>
-                        </strong>
-                    </p>
-                </content>
-            </shape>
-            <shape height="22" rotation="0" topLeftX="380" topLeftY="200" type="text" width="200">
-                <content>
-                    <p textAlign="center">
-                        <span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="16">国内战争</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="40" rotation="0" topLeftX="380" topLeftY="225" type="text" width="200">
-                <content verticalAlign="top">
-                    <p textAlign="center">
-                        <span color="rgb(156, 163, 175)" fontSize="12">革命与反革命的残酷斗争</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="10" rotation="0" topLeftX="830" topLeftY="176" type="ellipse" width="10">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-                <border color="rgb(255, 215, 0)" width="1"/>
-            </shape>
-            <shape height="24" rotation="0" topLeftX="740" topLeftY="140" type="text" width="200">
-                <content>
-                    <p textAlign="center">
-                        <strong>
-                            <span color="rgb(255, 215, 0)" fontFamily="黑体" fontSize="20">1930s</span>
-                        </strong>
-                    </p>
-                </content>
-            </shape>
-            <shape height="22" rotation="0" topLeftX="740" topLeftY="200" type="text" width="200">
-                <content>
-                    <p textAlign="center">
-                        <span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="16">社会主义建设</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="40" rotation="0" topLeftX="740" topLeftY="225" type="text" width="200">
-                <content verticalAlign="top">
-                    <p textAlign="center">
-                        <span color="rgb(156, 163, 175)" fontSize="12">新经济政策与工业化探索</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="1" rotation="0" topLeftX="48" topLeftY="300" type="rect" width="864">
-                <fill>
-                    <fillColor color="rgba(255, 215, 0, 0.2)"/>
-                </fill>
-            </shape>
-            <shape height="24" rotation="0" topLeftX="48" topLeftY="320" type="text" width="280">
-                <content>
-                    <p>
-                        <span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="18">作者：奥斯特洛夫斯基</span>
-                    </p>
-                </content>
-            </shape>
-            <icon height="16" iconType="iconpark/Peoples/user.svg" topLeftX="52" topLeftY="360" width="16">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-            </icon>
-            <shape height="20" topLeftX="76" topLeftY="358" type="text" width="260">
-                <content verticalAlign="middle">
-                    <p>
-                        <span color="rgb(209, 213, 219)" fontSize="13">工人家庭出身，投身革命浪潮</span>
-                    </p>
-                </content>
-            </shape>
-            <icon height="16" iconType="iconpark/Sports/torch.svg" topLeftX="52" topLeftY="390" width="16">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-            </icon>
-            <shape height="20" topLeftX="76" topLeftY="388" type="text" width="260">
-                <content verticalAlign="middle">
-                    <p>
-                        <span color="rgb(209, 213, 219)" fontSize="13">战场负伤致残，生命陷入黑暗</span>
-                    </p>
-                </content>
-            </shape>
-            <icon height="16" iconType="iconpark/Health/first-aid-kit.svg" topLeftX="52" topLeftY="420" width="16">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-            </icon>
-            <shape height="20" topLeftX="76" topLeftY="418" type="text" width="260">
-                <content verticalAlign="middle">
-                    <p>
-                        <span color="rgb(209, 213, 219)" fontSize="13">全身瘫痪、双目失明</span>
-                    </p>
-                </content>
-            </shape>
-            <icon height="16" iconType="iconpark/Edit/edit.svg" topLeftX="52" topLeftY="450" width="16">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-            </icon>
-            <shape height="20" topLeftX="76" topLeftY="448" type="text" width="260">
-                <content verticalAlign="middle">
-                    <p>
-                        <span color="rgb(209, 213, 219)" fontSize="13">以文学为武器，口述完成创作</span>
-                    </p>
-                </content>
-            </shape>
-            <img alt="奥斯特洛夫斯基青年时期" height="213" rotation="0" src="https://example.com/images/ostrovsky.png" topLeftX="360" topLeftY="320" width="160">
-                <border color="rgba(255, 215, 0, 0.5)" width="2"/>
-                <crop type="rect"/>
-            </img>
-            <shape height="24" rotation="0" topLeftX="552" topLeftY="320" type="text" width="360">
-                <content>
-                    <p>
-                        <span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="18">创作动机</span>
-                    </p>
-                </content>
-            </shape>
-            <shape height="16" rotation="0" topLeftX="552" topLeftY="350" type="rect" width="2">
-                <fill>
-                    <fillColor color="rgb(196, 30, 58)"/>
-                </fill>
-            </shape>
-            <shape height="120" rotation="0" topLeftX="562" topLeftY="350" type="text" width="350">
-                <content lineSpacing="multiple:1.6" verticalAlign="top">
-                    <p>
-                        <span color="rgb(209, 213, 219)" fontSize="13">在双目失明、全身瘫痪的逆境中，奥斯特洛夫斯基以自身经历为蓝本，用顽强的意志口述完成了这部不朽巨著。他将文学创作视为生命的延续和战斗的武器，旨在通过保尔·柯察金的形象，向青年一代传递坚不可摧的革命信念和超越个人痛苦的崇高人生价值观。</span>
-                    </p>
-                </content>
-            </shape>
-        </data>
-        <note>
-            <content>
-                <p>各位好，这一页将我们带回《钢铁是怎样炼成的》这部巨著诞生的波澜壮阔的时代。</p>
-                <p>上半部分展示了从1917年十月革命到1930年代苏联社会主义建设的宏大历史画卷。这是一个充满剧烈社会变革和残酷斗争的年代，也是英雄主义和理想主义精神熊熊燃烧的年代。正是这样的背景，孕育了小说的灵魂。</p>
-                <p>下半部分，我们聚焦于作者奥斯特洛夫斯基的个人经历。他的一生，本身就是一部比小说更震撼人心的传奇。从投身革命的青年，到因伤致残的战士，再到与命运抗争的文学巨匠。他的创作动机源于自身不屈的战斗精神，他希望用保尔的故事激励后人，在任何困境中都不要放弃理想，要将有限的生命投入到无限的为人类解放而斗争的事业中去。</p>
-                <p>通过了解这段历史和作者的生平，我们能更深刻地理解《钢铁是怎样炼成的》这部作品的伟大之处。</p>
-            </content>
-        </note>
-    </slide>
-</presentation>

skills/lark-slides/references/slides_xml_schema_definition.xml

@@ -3018,7 +3018,7 @@
 
           子元素(mermaid 与 svg 二选一):
           - mermaid: Mermaid 源码文本, 可使用 CDATA 包裹
-            适用场景: 流程图、时序图、思维导图、类图、甘特图、饼图等结构化图表
+            适用场景: 流程图、时序图、思维导图、类图、甘特图、ER 图、用户旅程等结构图
             特点: 用简短的文本声明描述图表逻辑, 由渲染引擎自动布局, 无需手动计算坐标
             示例: <mermaid><![CDATA[flowchart TD\n  A[开始] --> B[结束]]]></mermaid>
           - svg: SVG 内容

skills/lark-slides/references/troubleshooting.md

@@ -16,7 +16,7 @@
 遇到 `invalid param`、某一页创建失败、页面空白或布局错乱时，按顺序处理：
 
 1. 记录 `xml_presentation_id`，不要假设失败代表什么都没创建。
-2. 用 `xml_presentations.get` 回读，确认是否已有部分页面写入。
+2. 用 `slides +xml-get` 回读，确认是否已有部分页面写入。
 3. 检查失败页是否含未转义字符：`Q&A -> Q&amp;A`，文本 `<` / `>` 写成 `&lt;` / `&gt;`，属性 URL `a=1&b=2 -> a=1&amp;b=2`。
 4. 检查标签闭合、属性引号、`<content>` 结构，以及 `<slide>` 直接子元素。
 5. 页面空白、溢出、重叠或越界时，按 [validation-checklist.md](validation-checklist.md) 运行 XML 文本重叠检查，并人工核对越界、截断、图文压盖等视觉风险；工具当前只会报告 `xml_not_well_formed` / `bbox_overlap`。
@@ -46,14 +46,14 @@
 | 400 XML 格式错误 | XML 语法错误 | 检查标签闭合、属性引号、特殊字符转义 |
 | 400 请求包装错误 | `--data` 未按 schema 包装 | 检查是否传入 `xml_presentation.content` 或 `slide.content` |
 | 创建成功但页面空白 / 内容缺失 / 布局错乱 | 常见于 `--slides '[...]'` 的 shell 转义或长参数传递问题 | 改用两步创建，并在创建后立即读取 XML 验证 |
-| 403 权限不足 | 身份或 scope 不匹配 | 先检查是否误用了 bot 身份，再确认 scope 和文档权限 |
+| 403 权限不足 | scope 或文档权限不匹配 | 确认 scope 和文档权限；无权限时根据错误响应引导用户解决 |
 | 404 演示文稿不存在 | `xml_presentation_id` 不正确或无权限 | 检查 token；wiki URL 需先解析真实 `obj_token` |
 | 404 幻灯片不存在 | `slide_id` 不正确 | 重新读取 presentation 或 slide，确认最新 ID |
 | 400 无法删除唯一幻灯片 | 演示文稿至少保留一页 | 先创建新页，再删除旧页 |
 | 1061002 媒体上传 params error | slides 媒体上传参数不符合约定 | 用 `slides +media-upload`，不要手拼原生 `medias/upload_all`；slides 唯一可用 `parent_type` 是 `slide_file` |
-| 1061004 forbidden | 当前身份对演示文稿无编辑权限 | 确认 user/bot 对目标 PPT 有编辑权限；bot 常见于 PPT 非该 bot 创建 |
+| 1061004 forbidden | 当前用户对演示文稿无编辑权限 | 确认当前用户对目标 PPT 有编辑权限 |
 | 3350001 | XML 非 well-formed、XML 结构不符合服务端要求，或 replace 片段问题 | 优先检查未转义字符；replace 场景再看 `block_id` 和 `<content/>` |
-| 3350002 | `revision_id` 大于当前版本 | 用 `-1` 取当前版本，或重新读 `xml_presentations.get` 取最新 `revision_id` |
+| 3350002 | `revision_id` 大于当前版本 | 用 `-1` 取当前版本，或重新用 `slides +xml-get` 取最新 `revision_id` |
 | validation: unsafe file path | `--file` 给了绝对路径或上层路径 | `--file` 必须是 CWD 内相对路径；先 `cd` 到素材目录再执行 |
 
 ## Command-Specific References

skills/lark-slides/references/validation-checklist.md

@@ -7,7 +7,7 @@
 ## Required Flow
 
 1. 记录创建或编辑返回的 `xml_presentation_id`，以及已知的 `slide_id` / `revision_id`。
-2. 用 `xml_presentations.get` 回读全文 XML。
+2. 用 `slides +xml-get` 回读全文 XML 到本地文件。
 3. 检查实际页数是否符合计划或用户要求。
 4. 检查每页 `<data>` 内是否有预期主要元素。
 5. 检查没有明显空白页、破损页、缺失标题或缺失主视觉。
@@ -19,13 +19,15 @@
 回读命令：
 
 ```bash
-lark-cli slides xml_presentations get --as user \
-  --params '{"xml_presentation_id":"YOUR_ID"}'
+lark-cli slides +xml-get --as user \
+  --presentation "YOUR_ID" \
+  --output .lark-slides/plan/<deck-or-task-id>/readback.xml \
+  --json
 ```
 
 ## Automated XML Text Overlap Lint
 
-回读 XML 保存到本地文件后，优先运行 XML 语法和文本重叠静态检查：
+`slides +xml-get` 保存 XML 到本地文件后，优先运行 XML 语法和文本重叠静态检查：
 
 ```bash
 python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentation.xml>
@@ -44,6 +46,37 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 | `xml_not_well_formed` | XML 语法错误或文本未转义 | 修复标签闭合、属性引号、`&` / `<` / `>` 转义 |
 | `bbox_overlap` | 文本元素的估算绘制区域明显重叠 | 拉开文本坐标、缩小文本框/字号，或改成明确的分栏/分组结构 |
 
+## Screenshot QA
+
+获取页面截图后，必须使用 subagent 做视觉验收；主 agent 不要只凭 XML 回读或静态 lint 结论声称截图验收通过。验收时假设页面存在问题，主动寻找并报告所有风险，包括轻微问题。
+
+把截图路径、每页预期内容和以下中文提示交给 subagent：
+
+```text
+请逐页目视检查这些幻灯片截图。先假设存在问题，并尽量找出它们。
+
+重点检查：
+- 元素重叠：文字与形状、图片或图表互相遮挡，线条穿过文字，卡片或标签堆叠。
+- 文本溢出或被裁切：靠近页面边缘、文本框边界或卡片边界处被截断。
+- 装饰元素位置错误：分割线、强调线或标签底板按单行文字布置，但标题或正文换行后压住文字或距离异常。
+- 来源标注、页脚或页码与上方内容碰撞。
+- 元素距离过近：相邻元素间距明显不足，卡片或分区几乎贴在一起；按 960x540 画布估算，小于约 25-30 px 的间隔通常要标记。
+- 间距不均：局部留白过大，另一处过于拥挤。
+- 页面边距不足：主体内容贴近幻灯片边缘；按 960x540 画布估算，小于约 45-50 px 的外边距通常要标记。
+- 列、卡片、图标或同类元素没有稳定对齐。
+- 图片、图表或 whiteboard 渲染异常：空白、变形、低清、关键内容不可读或预期图形缺失。
+- 文本对比度不足，例如浅灰文字放在米色或浅色背景上。
+- 图标对比度不足，例如深色图标放在深色背景上，且没有浅色圆形或底板承托。
+- 文本框过窄，导致不必要的频繁换行。
+- 残留占位符、模板默认文字或未替换内容。
+
+对每一页分别列出发现的问题或可疑区域，即使只是轻微问题也要记录。
+
+报告所有发现的问题，包括轻微问题。
+```
+
+subagent 返回后，主 agent 必须根据问题严重度决定是否修复：空白页、破图、文字遮挡、明显裁切、低对比不可读、占位符残留等必须先修复再交付；轻微间距或对齐问题如果不修复，最终验证记录要说明已知风险。
+
 ## Page Count And Structure
 
 - 实际页数必须等于用户要求或 `slide_plan.json` 的页数。
@@ -101,7 +134,7 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 
 ```text
 验证记录：
-- 回读：已执行 xml_presentations.get，实际页数 N / 预期 N。
+- 回读：已执行 slides +xml-get，实际页数 N / 预期 N。
 - 关键页：架构解释 / Self-Attention / 对比或演进 / 总结页均存在。
 - 结构：检查了主要 shape/img/table/chart 元素，无明显空白页或破损页。
 - 布局：检查了标题层级、主视觉、重叠/越界/文本溢出风险。

skills/lark-slides/references/visual-planning.md

@@ -2,7 +2,7 @@
 
 新建演示文稿或大幅改写页面时，在 `slide_plan.json` 完成后、生成 XML 前读取本文件。目标是让 `layout_type`、`visual_focus`、`text_density` 变成实际页面几何，而不是只写在 plan 里。
 
-默认画布按 `960 x 540` 规划。已有页面回读 XML 可以影响具体坐标，但不能覆盖这些原则：页面要有主视觉区域、文本要受密度约束、不同 `layout_type` 必须产生明显不同的坐标结构。
+默认画布按 `960 x 540` 规划。模板 XML 可以覆盖具体坐标，但不能覆盖这些原则：页面要有主视觉区域、文本要受密度约束、不同 `layout_type` 必须产生明显不同的坐标结构。
 
 ## Core Rules
 
@@ -131,6 +131,7 @@ Purpose: make one metric or fact memorable.
 
 Geometry:
 - Reserve the largest object for the metric: font size often `64-110`, region at least `300 x 120`.
+- Set `autoFit="normal-auto-fit"` on the metric's `<content>` so an oversized number shrinks to fit its box instead of overflowing.
 - Pair the number with one explanation and optional 2-3 small supporting labels.
 - Do not bury the number in a bullet list or small card.
 
@@ -168,7 +169,7 @@ Text:
 
 Purpose: explain components, dependencies, or system flow.
 
-Implementation: prefer `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` only as fallback.
+Implementation: prefer Mermaid `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` as fallback.
 
 Geometry:
 - Main visual area should be a diagram, not prose.
@@ -184,7 +185,7 @@ Text:
 
 Purpose: show operational steps, workflow, or cause-effect path.
 
-Implementation: prefer `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` only as fallback.
+Implementation: prefer Mermaid `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` as fallback.
 
 Geometry:
 - Use numbered steps connected by arrows or lines.

skills/lark-slides/references/visual-styles.md

@@ -0,0 +1,46 @@
+# 特殊视觉风格
+
+当用户明确点名以下某种风格时，本文对应小节的规格**优先于** `visual-planning.md` 的默认审美设定；仍需遵守画布 960×540、留白、文字不溢出等硬约束。颜色一律用 `rgba(R,G,B,A)`，深浅背景都友好。
+
+适用触发：用户说“咨询风 / 麦肯锡风 / BCG 风 / 战略咨询风 / 数据报告风”，或“豆包风 / doubao 风 / 豆包 PPT 那种”，或直接贴出属于这两类风格的参考图/链接。
+
+---
+
+## 咨询风（McKinsey / BCG 战略咨询）
+
+要求：一张专业、高密度的咨询演示幻灯片，设计风格需融合顶尖战略咨询公司（麦肯锡/BCG）的风格与高端出版物的美学。
+	
+核心内容与布局：
+- 丰富的数据可视化：幻灯片需填充复杂、精确的图表（堆叠柱状图、瀑布图或折线图）以及包含行和列的详细数据表。
+- 结构化框架：包含战略图表或由细致、简洁线条构成的 2x2 矩阵。
+- 高信息密度：布局精致且采用多栏设计，模仿真实的商业分析文稿，而非仅仅是一个空白的封面页。
+	
+视觉风格：
+- 美学：科技极简主义，但信息承载量大。风格干净、锐利且具权威感。
+- 字体：主标题使用衬线体（如 Times New Roman），以营造高级财务报告的质感；图表标签和数据数字使用简洁的无衬线体。
+- 配色：纯白背景。文字为清晰的黑色。图表和图形装饰使用深皇家蓝（Deep Royal Blue）和不同深浅的灰色来体现数据层级。
+- 图形：表格使用极细的边框线，图表使用精确的矢量线条。
+
+
+---
+
+## 豆包风（豆包数据卡片）
+
+要求：一张信息密度巨高的图文卡片化布局幻灯片，追求充实饱满、图文丰富、可逐行细读的版面。
+
+核心内容与布局：
+- **信息密度巨高（至关重要）：除封面和分节页外，每个内容页都塞满多张图文卡片，宁可密而满，不要空而疏，不要留白。**
+- 卡片化布局：方角卡片按多行网格铺满版面（网格数、图文比例按内容变化，避免每页雷同）；每个卡片不是短标签，而是“标题 + 完整说明”，像浓缩的分析文稿。
+- 卡片版式：卡片用窄条点缀（贴任意一边或不加），采用“锚点（语义图标或编号）+ 标题 + 细分隔线（可选）+ 正文”的结构。
+- 文字卡片：内容页正文量级必须达到 400-600 中文字，分布在 4-12 个卡片，每个文字卡片都塞满文字内容，宁可密而满，不要空而疏。
+- 图片卡片：内容页必须包含图片卡片，多数内容页目标 1-3 张，图片卡片与文字卡片组成网格，缺少图片卡片时必须用生图工具生成配图补足。
+- 图标密集镶嵌：文字卡片、列表项和指标旁大量内嵌语义图标（部分放在圆形 / 方形底里）作为视觉锚点，让高密度文字也有图形节奏，而不是成片纯文字块。
+- 数据驱动：数据页密集使用原生图表（饼图、环形图、柱状、折线、组合），图表常与卡片网格并排成半栏布局（如左图右卡或上表下卡）。
+- 关键指标突出：KPI 用比正文稍大的数字呈现，不要过大，下方配小字标签与简短解读。
+- 防文本溢出：所有承载突出信息和密集文字的 `<content>` 必须设置 `autoFit="normal-auto-fit"`，字号会在框内自动缩排以防溢出。
+
+视觉风格：
+- 美学：干净、明亮、清爽但信息饱满；纯平无渐变，靠卡片、分隔线和对齐网格在高密度下维持秩序感。
+- 字体：全篇以无衬线体（思源黑体）为主，封面或关键强调可少量使用衬线体。
+- 字号：使用偏小的正文字号以容纳更多文字，提高信息密度。
+- 配色：控制配色数量，避免色彩泛滥导致画面杂乱，1 个主色，1-2 个辅助色，1 个强调色。

skills/lark-slides/references/xml-format-guide.md

@@ -1,369 +0,0 @@
-# XML 格式指南
-
-本文档基于 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 整理，说明飞书 Slides XML Schema（SML 2.0）的核心结构和常用写法。
-
-## 基本结构
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
-  <title>演示文稿标题</title>
-  <slide>
-    <style>
-      <fill>
-        <fillColor color="rgb(245, 245, 245)"/>
-      </fill>
-    </style>
-    <data>
-      <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
-        <content textType="title">
-          <p>主标题</p>
-        </content>
-      </shape>
-    </data>
-    <note>
-      <content textType="body">
-        <p>这是演讲者备注。</p>
-      </content>
-    </note>
-  </slide>
-</presentation>
-```
-
-## 根元素
-
-### `<presentation>`
-
-协议标准写法应带命名空间 `http://www.larkoffice.com/sml/2.0`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证。
-
-**属性：**
-
-| 属性 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `width` | positiveInteger | 是 | 演示文稿宽度，如 `960` |
-| `height` | positiveInteger | 是 | 演示文稿高度，如 `540` |
-| `id` | string | 否 | 演示文稿标识 |
-
-**子元素：**
-
-| 元素 | 必需 | 说明 |
-|------|------|------|
-| `<title>` | 否 | 演示文稿标题 |
-| `<theme>` | 否 | 全局主题 |
-| `<slide>` | 是 | 幻灯片页面，至少 1 页，最多 100 页 |
-
-## 主题
-
-### `<theme>`
-
-`<theme>` 当前包含两部分：
-
-- `<background>`：演示文稿级背景填充
-- `<textStyles>`：主题文本样式集合
-
-`<textStyles>` 下可选子元素：
-
-- `<title>`
-- `<headline>`
-- `<sub-headline>`
-- `<body>`
-- `<caption>`
-
-这些元素定义的是主题默认样式，不是页面结构。常用属性：
-
-| 属性 | 说明 |
-|------|------|
-| `fontFamily` | 字体 |
-| `fontSize` | 字号 |
-| `fontColor` | 字体颜色 |
-
-## 幻灯片元素
-
-### `<slide>`
-
-单张幻灯片的结构比较严格。
-
-**属性：**
-
-| 属性 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `id` | string | 否 | 幻灯片标识 |
-
-**直接子元素只有：**
-
-| 元素 | 必需 | 说明 |
-|------|------|------|
-| `<style>` | 否 | 页面样式 |
-| `<data>` | 否 | 页面元素容器 |
-| `<note>` | 否 | 演讲者备注 |
-
-这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。
-
-## 文本内容模型
-
-### `<content>`
-
-实际页面文本通常通过 `<content>` 表达，常见位置有：
-
-- `shape` 内部
-- `table/td` 内部
-- `note` 内部
-
-**常用属性：**
-
-| 属性 | 说明 |
-|------|------|
-| `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` |
-| `verticalAlign` | 垂直对齐 |
-| `textAlign` | 水平对齐 |
-| `lineSpacing` | 行间距 |
-| `fontSize` | 字号 |
-| `fontFamily` | 字体 |
-| `color` | 字体颜色 |
-| `bold` / `italic` / `underline` / `strikethrough` | 内容级样式 |
-| `wrap` | 是否自动换行 |
-
-**可包含的子元素：**
-
-- `<p>`
-- `<ul>`
-- `<ol>`
-
-### `<p>`
-
-`<p>` 是段落元素，可混排纯文本和内联标签：
-
-- `<br/>`
-- `<strong>`
-- `<em>`
-- `<u>`
-- `<span>`
-- `<del>`
-- `<a>`
-- `<shadow>`
-- `<outline>`
-
-示例：
-
-```xml
-<content textType="body" textAlign="left">
-  <p>普通文本 <strong>加粗</strong> <em>斜体</em> <a href="https://example.com">链接</a></p>
-  <ul>
-    <li><p>列表项 1</p></li>
-    <li><p>列表项 2</p></li>
-  </ul>
-</content>
-```
-
-## 常用页面元素
-
-所有页面元素都放在 `<data>` 中。
-
-### `<shape>`
-
-`shape` 可表示普通形状，也可表示文本框。文本框推荐使用 `type="text"`。
-
-```xml
-<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
-  <content textType="title">
-    <p>主标题</p>
-  </content>
-</shape>
-```
-
-```xml
-<shape type="rect" topLeftX="700" topLeftY="120" width="180" height="120">
-  <fill>
-    <fillColor color="rgba(100, 149, 237, 0.25)"/>
-  </fill>
-  <border color="rgb(100, 149, 237)" width="2"/>
-</shape>
-```
-
-**属性：**
-
-| 属性 | 必需 | 说明 |
-|------|------|------|
-| `type` | 是 | 形状类型，`text` 表示文本框 |
-| `topLeftX` | 是 | 左上角 X 坐标 |
-| `topLeftY` | 是 | 左上角 Y 坐标 |
-| `width` | 是 | 宽度 |
-| `height` | 是 | 高度 |
-| `rotation` | 否 | 旋转角度 |
-| `flipX` / `flipY` | 否 | 翻转 |
-| `alpha` | 否 | 透明度 |
-
-**可选子元素：**
-
-- `<fill>`
-- `<border>`
-- `<reflection>`
-- `<shadow>`
-- `<content>`
-
-### `<line>`
-
-```xml
-<line startX="100" startY="200" endX="420" endY="200">
-  <border color="rgb(43, 47, 54)" width="2"/>
-</line>
-```
-
-`line` 使用的是 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。
-
-### `<img>`
-
-```xml
-<img src="file_token_or_url" topLeftX="100" topLeftY="220" width="320" height="180"/>
-```
-
-`img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。
-
-`src` 只接受两种值：
-
-| `src` 形式 | 说明 |
-|---|---|
-| `file_token`（如 `boxcnXXXXXXXXXXXXXXXXXXXXXX`） | 通过 `slides +media-upload` 上传后返回的 token |
-| `@<本地路径>`（如 `@./assets/chart.png`） | **仅在 `slides +create --slides` 中可用**：CLI 会自动上传该文件并替换为 file_token |
-
-> **禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，`src="https://..."` 在 PPT 里通常显示破图。要用网图必须先 `curl`/下载到 CWD 内，再走上传流程拿 `file_token`。
-
-本地图片的两种姿势：
-
-- **新建带图 PPT**：`+create --slides` 里直接写 `src="@./pic.png"`，CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token
-- **给已有 PPT 加带图新页**：先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token，再用 token 写进 `xml_presentation.slide create` 的 XML
-
-### `<icon>`
-
-```xml
-<icon iconType="iconpark/Base/setting.svg" topLeftX="440" topLeftY="220" width="32" height="32"/>
-```
-
-### `<table>`
-
-表格结构为：
-
-- `<table>`
-- `<colgroup>` / `<tr>`
-- `<tr>` 内为 `<td>`
-- `<td>` 内可放 `<content>`
-
-### `<chart>`
-
-图表元素必须至少包含：
-
-- `<chartPlotArea>`
-- `<chartData>`
-
-同时还可以包含：
-
-- `<chartTitle>`
-- `<chartSubTitle>`
-- `<chartStyle>`
-- `<chartLegend>`
-- `<chartTooltip>`
-
-如果要写图表 XML，建议直接以 XSD 为准，不要自行发明更简化的 chart DSL。
-
-## 样式元素
-
-### `<fill>`
-
-```xml
-<fill>
-  <fillColor color="rgb(100, 149, 237)"/>
-</fill>
-```
-
-### `<border>`
-
-```xml
-<border color="rgb(0, 0, 0)" width="2" dashArray="solid"/>
-```
-
-### 颜色格式
-
-```xml
-<fillColor color="rgb(255, 0, 0)"/>
-<fillColor color="rgba(255, 0, 0, 0.5)"/>
-<fillColor color="linear-gradient(90deg, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/>
-<fillColor color="radial-gradient(circle at 50% 50%, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/>
-```
-
-## 演讲者备注
-
-### `<note>`
-
-```xml
-<note>
-  <content textType="body">
-    <p>这是演讲者备注内容。</p>
-  </content>
-</note>
-```
-
-## 完整示例
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
-  <title>季度报告</title>
-  <theme>
-    <textStyles>
-      <title fontFamily="思源黑体" fontSize="54" fontColor="rgba(0, 0, 0, 1)"/>
-      <body fontFamily="思源黑体" fontSize="18" fontColor="rgba(43, 47, 54, 1)"/>
-    </textStyles>
-  </theme>
-  <slide>
-    <style>
-      <fill>
-        <fillColor color="rgb(245, 245, 245)"/>
-      </fill>
-    </style>
-    <data>
-      <shape type="text" topLeftX="80" topLeftY="72" width="760" height="100">
-        <content textType="title">
-          <p>2024 年第一季度报告</p>
-        </content>
-      </shape>
-      <shape type="text" topLeftX="80" topLeftY="200" width="520" height="180">
-        <content textType="body">
-          <p>核心指标</p>
-          <ul>
-            <li><p>用户增长：+25%</p></li>
-            <li><p>收入增长：+30%</p></li>
-            <li><p>市场份额：15%</p></li>
-          </ul>
-        </content>
-      </shape>
-      <shape type="rect" topLeftX="660" topLeftY="180" width="180" height="140">
-        <fill>
-          <fillColor color="rgba(100, 149, 237, 0.25)"/>
-        </fill>
-        <border color="rgb(100, 149, 237)" width="2"/>
-      </shape>
-    </data>
-    <note>
-      <content textType="body">
-        <p>讲到增长率时补充样本范围。</p>
-      </content>
-    </note>
-  </slide>
-</presentation>
-```
-
-## 最佳实践
-
-1. 始终带上命名空间 `xmlns="http://www.larkoffice.com/sml/2.0"`
-2. 用 `shape type="text"` + `content` 表达页面文本
-3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名
-4. 优先使用 `rgb` / `rgba` 颜色格式
-5. 特殊字符按 XML 规则转义
-6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"`
-
-## 参考文档
-
-- [xml-schema-quick-ref.md](xml-schema-quick-ref.md)
-- [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)
-- [examples.md](examples.md)
-- [slides_demo.xml](slides_demo.xml)

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

@@ -1,6 +1,6 @@
 # XML Schema 快速参考
 
-本文档是 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 的精简版摘要；如果两者不一致，以 XSD 原文为准。
+本文档是 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 的精简版摘要，并合并了常用 XML 格式写法；如果两者不一致，以 XSD 原文为准。
 
 ## 最重要的规则
 
@@ -30,25 +30,31 @@
 
 | 属性 | 必需 | 说明 |
 |------|------|------|
-| `width` | 是 | 演示文稿宽度，正整数 |
-| `height` | 是 | 演示文稿高度，正整数 |
+| `width` | 是 | 演示文稿宽度，正整数，标准 16:9 页面建议使用 `960` |
+| `height` | 是 | 演示文稿高度，正整数，标准 16:9 页面建议使用 `540` |
 | `id` | 否 | 演示文稿标识 |
 
 **子元素：** `<title>?`, `<theme>?`, `<slide>+`
 
-## slide 元素
-
-| 属性 | 必需 | 说明 |
-|------|------|------|
-| `id` | 否 | 幻灯片标识 |
-
-**子元素：**
-- `<style>?` - 页面样式，目前可放 `<fill>`
-- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`whiteboard`、`undefined`
-- `<note>?` - 演讲者备注，内部可放 `<content>`
+`<slide>` 至少 1 页，最多 100 页。
 
 ## theme 与文本类型
 
+`<theme>` 当前包含两部分：
+
+- `<background>`：演示文稿级背景填充
+- `<textStyles>`：主题文本样式集合
+
+`<textStyles>` 下可选子元素包括 `<title>`、`<headline>`、`<sub-headline>`、`<body>`、`<caption>`。这些元素定义的是主题默认样式，不是页面结构。
+
+常用属性：
+
+| 属性 | 说明 |
+|------|------|
+| `fontFamily` | 字体 |
+| `fontSize` | 字号 |
+| `fontColor` | 字体颜色 |
+
 XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出现在：
 
 - `<theme><textStyles>...</textStyles></theme>` 中，作为主题文本样式
@@ -64,6 +70,20 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | `body` | 16 |
 | `caption` | 12 |
 
+## slide 元素
+
+| 属性 | 必需 | 说明 |
+|------|------|------|
+| `id` | 否 | 幻灯片标识 |
+
+**子元素：**
+
+- `<style>?` - 页面样式，目前可放 `<fill>`
+- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`whiteboard`、`undefined`
+- `<note>?` - 演讲者备注，内部可放 `<content>`
+
+这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。
+
 ## content 内容模型
 
 `<content>` 可出现在 `shape`、`table/td`、`note` 中，常用属性包括：
@@ -71,12 +91,14 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | 属性 | 说明 |
 |------|------|
 | `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` |
+| `verticalAlign` | 垂直对齐 |
 | `textAlign` | 文本对齐方式 |
 | `lineSpacing` | 行间距，schema 默认 `multiple:1.5` |
 | `fontSize` | 字号 |
 | `fontFamily` | 字体 |
 | `color` | 字体颜色 |
-| `bold` / `italic` / `underline` / `strikethrough` | 文本样式 |
+| `bold` / `italic` / `underline` / `strikethrough` | 内容级样式 |
+| `wrap` | 是否自动换行 |
 
 `<content>` 的子元素只能是：
 
@@ -84,7 +106,21 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 - `<ul>`
 - `<ol>`
 
-### content 示例
+### p 段落与内联标签
+
+`<p>` 是段落元素，可混排纯文本和内联标签：
+
+- `<br/>`
+- `<strong>`
+- `<em>`
+- `<u>`
+- `<span>`
+- `<del>`
+- `<a>`
+- `<shadow>`
+- `<outline>`
+
+示例：
 
 ```xml
 <content textType="body" textAlign="left">
@@ -98,8 +134,20 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 ## data 常用元素
 
+所有页面元素都放在 `<data>` 中。
+
 ### shape
 
+`shape` 可表示普通形状，也可表示文本框。文本框推荐使用 `type="text"`。
+
+```xml
+<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
+  <content textType="title">
+    <p>主标题</p>
+  </content>
+</shape>
+```
+
 ```xml
 <shape type="rect" topLeftX="120" topLeftY="120" width="240" height="120">
   <fill>
@@ -117,6 +165,16 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | `width` | 是 | 宽度 |
 | `height` | 是 | 高度 |
 | `rotation` | 否 | 旋转角度 |
+| `flipX` / `flipY` | 否 | 翻转 |
+| `alpha` | 否 | 透明度 |
+
+可选子元素：
+
+- `<fill>`
+- `<border>`
+- `<reflection>`
+- `<shadow>`
+- `<content>`
 
 ### line
 
@@ -126,14 +184,23 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 </line>
 ```
 
+`line` 使用的是 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。
+
 ### img
 
 ```xml
 <img src="file_token_or_url" topLeftX="80" topLeftY="120" width="320" height="180"/>
 ```
 
+`img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。
+
 `src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（仅 `+create --slides` 自动上传并替换）。**禁止使用 http(s) 外链 URL**——飞书 slides 渲染端不会代理外链图，外链 src 在 PPT 里通常不显示。本地图片详见 [lark-slides-create.md](lark-slides-create.md#本地图片path-占位符) / [lark-slides-media-upload.md](lark-slides-media-upload.md)。
 
+本地图片的两种姿势：
+
+- 新建带图 PPT：`+create --slides` 里直接写 `src="@./pic.png"`，CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token
+- 给已有 PPT 加带图新页：先 `slides +media-upload --file ./pic.png --presentation $PID` 拿 token，再用 token 写进 `xml_presentation.slide create` 的 XML
+
 > **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。
 
 ### icon
@@ -144,10 +211,85 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 `iconType` 必须来自已验证的 IconPark 路径。需要语义图标时，先运行 `scripts/iconpark_tool.py search --query "<语义>"`，不要凭记忆拼路径。更多规则见 [iconpark.md](iconpark.md)。
 
+### table
+
+表格结构为：
+
+- `<table>`
+- `<colgroup>` / `<tr>`
+- `<tr>` 内为 `<td>`
+- `<td>` 内可放 `<content>`
+
+### chart
+
+图表元素必须至少包含：
+
+- `<chartPlotArea>`
+- `<chartData>`
+
+同时还可以包含：
+
+- `<chartTitle>`
+- `<chartSubTitle>`
+- `<chartStyle>`
+- `<chartLegend>`
+- `<chartTooltip>`
+
+完整图表类型覆盖示例见 [slides_chart_demo.xml](slides_chart_demo.xml)，其中包含柱状、条形、折线、面积、饼 / 环、雷达等原生 `<chart>` 示例，以及散点、气泡、漏斗、帕累托、瀑布等 `<whiteboard>` SVG 图表示例。
+
+组合图示例：
+
+```xml
+<chart width="556" height="350" topLeftX="42" topLeftY="132">
+  <chartPlotArea>
+    <chartPlot type="combo">
+      <chartExtra/>
+      <chartSeriesList>
+        <chartSeries index="1" comboType="column"/>
+        <chartSeries index="2" comboType="line" yAxisPosition="right">
+          <chartTooltip format="0%"/>
+        </chartSeries>
+      </chartSeriesList>
+    </chartPlot>
+    <chartAxes>
+      <chartAxis type="x">
+        <chartLabel fontSize="10"/>
+      </chartAxis>
+      <chartAxis type="y" position="left">
+        <chartGridLine color="rgb(226, 232, 240)"/>
+        <chartLabel fontSize="10"/>
+      </chartAxis>
+      <chartAxis type="y" position="right">
+        <chartLabel fontSize="10" format="0%"/>
+      </chartAxis>
+    </chartAxes>
+  </chartPlotArea>
+  <chartLegend position="bottom" fontSize="11"/>
+  <chartData>
+    <dim1>
+      <chartField name="季度">24Q1,24Q2,24Q3,24Q4,25Q1,25Q2,25Q3,25Q4</chartField>
+    </dim1>
+    <dim2>
+      <chartField name="营收">180,195,210,245,220,238,258,296</chartField>
+      <chartField name="增速">0.08,0.12,0.15,0.18,0.22,0.22,0.23,0.21</chartField>
+    </dim2>
+  </chartData>
+  <chartTitle fontSize="12" color="rgba(15, 30, 58, 1)" bold="true">营收（亿美元, 左轴） · 同比增速（%, 右轴）</chartTitle>
+  <chartStyle>
+    <chartBackground color="rgba(0, 0, 0, 0)"/>
+    <chartBorder color="rgb(222, 224, 227)" width="0"/>
+    <chartColorTheme>
+      <color value="rgb(28, 71, 120)"/>
+      <color value="rgb(240, 129, 54)"/>
+    </chartColorTheme>
+  </chartStyle>
+</chart>
+```
+
 ### whiteboard
 
 ```xml
-<!-- SVG 模式：数据图表、装饰元素 -->
+<!-- SVG 模式：<chart> 不支持的图表或自定义视觉、装饰元素 -->
 <whiteboard topLeftX="580" topLeftY="120" width="340" height="280">
   <svg xmlns="http://www.w3.org/2000/svg">
     <rect x="60" y="80" width="40" height="140" rx="3" fill="rgba(59,130,246,0.85)"/>
@@ -231,12 +373,69 @@ Mermaid 模式：内容用 `<![CDATA[...]]>` 包裹，避免 `[`、`>`、`-->`
 </note>
 ```
 
+## 完整示例
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+  <title>季度报告</title>
+  <theme>
+    <textStyles>
+      <title fontFamily="思源黑体" fontSize="54" fontColor="rgba(0, 0, 0, 1)"/>
+      <body fontFamily="思源黑体" fontSize="18" fontColor="rgba(43, 47, 54, 1)"/>
+    </textStyles>
+  </theme>
+  <slide>
+    <style>
+      <fill>
+        <fillColor color="rgb(245, 245, 245)"/>
+      </fill>
+    </style>
+    <data>
+      <shape type="text" topLeftX="80" topLeftY="72" width="760" height="100">
+        <content textType="title">
+          <p>2024 年第一季度报告</p>
+        </content>
+      </shape>
+      <shape type="text" topLeftX="80" topLeftY="200" width="520" height="180">
+        <content textType="body">
+          <p>核心指标</p>
+          <ul>
+            <li><p>用户增长：+25%</p></li>
+            <li><p>收入增长：+30%</p></li>
+            <li><p>市场份额：15%</p></li>
+          </ul>
+        </content>
+      </shape>
+      <shape type="rect" topLeftX="660" topLeftY="180" width="180" height="140">
+        <fill>
+          <fillColor color="rgba(100, 149, 237, 0.25)"/>
+        </fill>
+        <border color="rgb(100, 149, 237)" width="2"/>
+      </shape>
+    </data>
+    <note>
+      <content textType="body">
+        <p>讲到增长率时补充样本范围。</p>
+      </content>
+    </note>
+  </slide>
+</presentation>
+```
+
+## 最佳实践
+
+1. 始终带上命名空间 `xmlns="http://www.larkoffice.com/sml/2.0"`
+2. 用 `shape type="text"` + `content` 表达页面文本
+3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名
+4. 优先使用 `rgb` / `rgba` 颜色格式；渐变必须使用 `rgba()` 且带百分比停靠点
+5. 特殊字符按 XML 规则转义
+6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"`
+
 ## 详细参考
 
 - [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)
-- [xml-format-guide.md](xml-format-guide.md)
-- [examples.md](examples.md)
-- [slides_demo.xml](slides_demo.xml)
+- [slides_chart_demo.xml](slides_chart_demo.xml)
 
 ## Schema 版本信息
 

skills/lark-slides/scripts/xml_text_overlap_lint_test.py

@@ -3,12 +3,16 @@
 from __future__ import annotations
 
 import unittest
+from pathlib import Path
 
 import xml_text_overlap_lint
 
 
+TEMPLATES_DIR = Path(__file__).resolve().parents[1] / "assets" / "templates"
+
+
 class XmlTextOverlapLintTest(unittest.TestCase):
-    def assertNoXmlTextOverlapLintIssues(self, result: dict, sample_name: str) -> None:
+    def assertNoXmlTextOverlapLintIssues(self, result: dict, template_path: Path) -> None:
         issue_summaries = []
         for slide in result.get("slides", []):
             for issue in slide.get("issues", []):
@@ -21,64 +25,24 @@ class XmlTextOverlapLintTest(unittest.TestCase):
         self.assertEqual(
             result["summary"]["error_count"],
             0,
-            f"{sample_name} has XML text overlap lint errors:\n" + "\n".join(issue_summaries),
+            f"{template_path.name} has XML text overlap lint errors:\n" + "\n".join(issue_summaries),
         )
         self.assertEqual(
             result["summary"]["warning_count"],
             0,
-            f"{sample_name} has XML text overlap lint warnings:\n" + "\n".join(issue_summaries),
+            f"{template_path.name} has XML text overlap lint warnings:\n" + "\n".join(issue_summaries),
         )
 
-    def test_xml_text_overlap_lint_accepts_inline_fixture_xml_samples(self) -> None:
-        samples = {
-            "image-led-cover": """
-                <presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
-                  <slide xmlns="http://www.larkoffice.com/sml/2.0">
-                    <style><fill><fillColor color="rgb(15,23,42)"/></fill></style>
-                    <data>
-                      <img src="tok" topLeftX="560" topLeftY="0" width="400" height="540"/>
-                      <shape type="text" topLeftX="64" topLeftY="150" width="420" height="70">
-                        <content textType="title"><p><span fontSize="42">Quarterly Review</span></p></content>
-                      </shape>
-                      <shape type="text" topLeftX="64" topLeftY="235" width="420" height="36">
-                        <content textType="sub-headline"><p><span fontSize="20">Focus, progress, and next steps</span></p></content>
-                      </shape>
-                    </data>
-                  </slide>
-                </presentation>
-            """,
-            "content-grid": """
-                <presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
-                  <slide xmlns="http://www.larkoffice.com/sml/2.0">
-                    <data>
-                      <shape type="text" topLeftX="60" topLeftY="44" width="620" height="46">
-                        <content textType="title"><p><span fontSize="30">Execution Snapshot</span></p></content>
-                      </shape>
-                      <shape type="rect" topLeftX="60" topLeftY="126" width="250" height="150"/>
-                      <shape type="text" topLeftX="84" topLeftY="152" width="200" height="36">
-                        <content textType="headline"><p><span fontSize="22">Plan</span></p></content>
-                      </shape>
-                      <shape type="rect" topLeftX="355" topLeftY="126" width="250" height="150"/>
-                      <shape type="text" topLeftX="379" topLeftY="152" width="200" height="36">
-                        <content textType="headline"><p><span fontSize="22">Build</span></p></content>
-                      </shape>
-                      <shape type="rect" topLeftX="650" topLeftY="126" width="250" height="150"/>
-                      <shape type="text" topLeftX="674" topLeftY="152" width="200" height="36">
-                        <content textType="headline"><p><span fontSize="22">Launch</span></p></content>
-                      </shape>
-                    </data>
-                  </slide>
-                </presentation>
-            """,
-        }
-        self.assertTrue(samples)
-        for sample_name, sample_xml in samples.items():
-            with self.subTest(sample=sample_name):
+    def test_xml_text_overlap_lint_accepts_all_template_xml_files(self) -> None:
+        template_paths = sorted(TEMPLATES_DIR.glob("*.xml"))
+        self.assertTrue(template_paths)
+        for template_path in template_paths:
+            with self.subTest(template=template_path.name):
                 result = xml_text_overlap_lint.lint_xml(
-                    sample_xml,
-                    sample_name,
+                    template_path.read_text(encoding="utf-8"),
+                    str(template_path),
                 )
-                self.assertNoXmlTextOverlapLintIssues(result, sample_name)
+                self.assertNoXmlTextOverlapLintIssues(result, template_path)
 
     def test_lint_xml_reports_unescaped_ampersand_in_text(self) -> None:
         result = xml_text_overlap_lint.lint_xml(

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.

tests/cli_e2e/drive/drive_permission_get_setting_test.go

@@ -1,125 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package drive
-
-import (
-	"context"
-	"strings"
-	"testing"
-	"time"
-
-	clie2e "github.com/larksuite/cli/tests/cli_e2e"
-	"github.com/stretchr/testify/require"
-	"github.com/tidwall/gjson"
-)
-
-func TestDrive_PermissionGetSettingDryRun(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")
-
-	tests := []struct {
-		name     string
-		args     []string
-		wantURL  string
-		wantType string
-	}{
-		{
-			name: "bare folder token",
-			args: []string{
-				"drive", "+permission-get-setting",
-				"--token", "fldE2E001",
-				"--type", "folder",
-				"--dry-run",
-			},
-			wantURL:  "/open-apis/drive/v2/permissions/fldE2E001/public",
-			wantType: "folder",
-		},
-		{
-			name: "folder URL",
-			args: []string{
-				"drive", "+permission-get-setting",
-				"--token", "https://example.feishu.cn/drive/folder/fldE2E001?from=share",
-				"--dry-run",
-			},
-			wantURL:  "/open-apis/drive/v2/permissions/fldE2E001/public",
-			wantType: "folder",
-		},
-		{
-			name: "docx URL",
-			args: []string{
-				"drive", "+permission-get-setting",
-				"--token", "https://example.feishu.cn/docx/doxE2E001",
-				"--dry-run",
-			},
-			wantURL:  "/open-apis/drive/v2/permissions/doxE2E001/public",
-			wantType: "docx",
-		},
-	}
-
-	for _, temp := range tests {
-		tt := temp
-		t.Run(tt.name, func(t *testing.T) {
-			ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-			t.Cleanup(cancel)
-
-			result, err := clie2e.RunCmd(ctx, clie2e.Request{
-				Args:      tt.args,
-				DefaultAs: "bot",
-			})
-			require.NoError(t, err)
-			result.AssertExitCode(t, 0)
-
-			out := result.Stdout
-			if got := gjson.Get(out, "api.0.method").String(); got != "GET" {
-				t.Fatalf("method = %q, want GET\nstdout:\n%s", got, out)
-			}
-			if got := gjson.Get(out, "api.0.url").String(); got != tt.wantURL {
-				t.Fatalf("url = %q, want %q\nstdout:\n%s", got, tt.wantURL, out)
-			}
-			if got := gjson.Get(out, "api.0.params.type").String(); got != tt.wantType {
-				t.Fatalf("params.type = %q, want %q\nstdout:\n%s", got, tt.wantType, out)
-			}
-			if gjson.Get(out, "folder_token").Exists() {
-				t.Fatalf("folder_token exists in dry-run output, want omitted\nstdout:\n%s", out)
-			}
-		})
-	}
-}
-
-func TestDrive_PermissionGetSettingWorkflow(t *testing.T) {
-	parentT := t
-	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
-	t.Cleanup(cancel)
-
-	folderName := "lark-cli-e2e-drive-permission-get-setting-" + clie2e.GenerateSuffix()
-	folderToken := createDriveFolderOrSkipPermission(t, parentT, ctx, folderName)
-
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"drive", "+permission-get-setting",
-			"--token", folderToken,
-			"--type", "folder",
-			"--format", "json",
-		},
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	if result.ExitCode != 0 {
-		combinedOutput := strings.ToLower(result.Stdout + "\n" + result.Stderr)
-		if strings.Contains(combinedOutput, "docs:permission.setting:read") ||
-			strings.Contains(combinedOutput, "app scope not enabled") ||
-			strings.Contains(combinedOutput, "missing required scope") ||
-			strings.Contains(combinedOutput, "99991672") {
-			t.Skipf("skip drive permission setting workflow due to missing bot scope docs:permission.setting:read: %s", strings.TrimSpace(result.Stdout+"\n"+result.Stderr))
-		}
-	}
-	result.AssertExitCode(t, 0)
-	result.AssertStdoutStatus(t, true)
-
-	if !gjson.Get(result.Stdout, "data.permission_public").Exists() {
-		t.Fatalf("permission_public missing in output\nstdout:\n%s", result.Stdout)
-	}
-}