fix(docs): preserve local image dimensions

Agents dropping to the raw `calendar events create/patch` API must convert
wall-clock time to Unix timestamps themselves. In UTC containers this silently
yields an 8-hour offset. Require explicit ISO 8601 offsets on +create/+update
--start/--end, and warn that raw-API timestamp conversion must specify the
target timezone instead of relying on the container default.

cmd/root_test.go

@@ -627,7 +627,7 @@ func TestApplyNeedAuthorizationHint_AppendsExistingHint(t *testing.T) {
 	authErr.Hint = "existing hint"
 	applyNeedAuthorizationHint(f, authErr)
 
-	want := "existing hint\ncurrent command requires scope(s): docx:document:create"
+	want := "existing hint\ncurrent command requires scope(s): docx:document:create, docs:document.media:upload, docx:document:write_only, docx:document:readonly"
 	if authErr.Hint != want {
 		t.Errorf("expected appended hint %q, got %q", want, authErr.Hint)
 	}

shortcuts/base/base_form_execute_test.go

@@ -4,6 +4,7 @@
 package base
 
 import (
+	"encoding/json"
 	"strings"
 	"testing"
 
@@ -250,7 +251,8 @@ func TestBaseFormQuestionsExecuteList(t *testing.T) {
 				"total": 2,
 				"questions": []interface{}{
 					map[string]interface{}{"id": "q_001", "title": "您的姓名", "required": true, "description": nil},
-					map[string]interface{}{"id": "q_002", "title": "您的年龄", "required": false, "description": nil},
+					map[string]interface{}{"id": "q_002", "title": "发票抬头", "required": false, "description": nil,
+						"visible_rule": map[string]interface{}{"logic": "and", "conditions": []interface{}{[]interface{}{"q_001", "==", "是"}}}},
 				},
 			},
 		},
@@ -258,9 +260,14 @@ func TestBaseFormQuestionsExecuteList(t *testing.T) {
 	if err := runShortcut(t, BaseFormQuestionsList, []string{"+form-questions-list", "--base-token", "app_x", "--table-id", "tbl_x", "--form-id", "vew_form1"}, factory, stdout); err != nil {
 		t.Fatalf("err=%v", err)
 	}
-	if got := stdout.String(); !strings.Contains(got, `"q_001"`) || !strings.Contains(got, `"total": 2`) {
+	got := stdout.String()
+	if !strings.Contains(got, `"q_001"`) || !strings.Contains(got, `"total": 2`) {
 		t.Fatalf("stdout=%s", got)
 	}
+	// The list output must forward visible_rule verbatim so agents can read existing display conditions.
+	if !strings.Contains(got, `"visible_rule"`) {
+		t.Fatalf("visible_rule missing from list output: %s", got)
+	}
 }
 
 func TestBaseFormQuestionsExecuteCreate(t *testing.T) {
@@ -296,11 +303,49 @@ func TestBaseFormQuestionsExecuteCreate(t *testing.T) {
 			t.Fatalf("expected error for invalid questions JSON")
 		}
 	})
+
+	t.Run("visible_rule passthrough", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		stub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/forms/vew_form1/questions",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"questions": []interface{}{
+						map[string]interface{}{"id": "q_new1", "title": "发票抬头"},
+					},
+				},
+			},
+		}
+		reg.Register(stub)
+		args := []string{"+form-questions-create", "--base-token", "app_x", "--table-id", "tbl_x", "--form-id", "vew_form1",
+			"--questions", `[{"type":"text","title":"发票抬头","visible_rule":{"logic":"and","conditions":[["是否需要发票","==","是"]]}}]`}
+		if err := runShortcut(t, BaseFormQuestionsCreate, args, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		var body struct {
+			Questions []map[string]interface{} `json:"questions"`
+		}
+		if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+			t.Fatalf("captured body json err=%v body=%s", err, string(stub.CapturedBody))
+		}
+		if len(body.Questions) != 1 {
+			t.Fatalf("questions=%#v", body.Questions)
+		}
+		rule, ok := body.Questions[0]["visible_rule"].(map[string]interface{})
+		if !ok {
+			t.Fatalf("visible_rule not forwarded verbatim: body=%s", string(stub.CapturedBody))
+		}
+		if rule["logic"] != "and" {
+			t.Fatalf("visible_rule logic not preserved: %#v", rule)
+		}
+	})
 }
 
 func TestBaseFormQuestionsExecuteUpdate(t *testing.T) {
 	factory, stdout, reg := newExecuteFactory(t)
-	reg.Register(&httpmock.Stub{
+	stub := &httpmock.Stub{
 		Method: "PATCH",
 		URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/forms/vew_form1/questions",
 		Body: map[string]interface{}{
@@ -311,15 +356,29 @@ func TestBaseFormQuestionsExecuteUpdate(t *testing.T) {
 				},
 			},
 		},
-	})
+	}
+	reg.Register(stub)
 	args := []string{"+form-questions-update", "--base-token", "app_x", "--table-id", "tbl_x", "--form-id", "vew_form1",
-		"--questions", `[{"id":"q_001","title":"更新后的问题","required":true}]`}
+		"--questions", `[{"id":"q_001","title":"更新后的问题","required":true,"visible_rule":{"logic":"and","conditions":[["q_002","==","是"]]}}]`}
 	if err := runShortcut(t, BaseFormQuestionsUpdate, args, factory, stdout); err != nil {
 		t.Fatalf("err=%v", err)
 	}
 	if got := stdout.String(); !strings.Contains(got, `"questions"`) || !strings.Contains(got, `"q_001"`) {
 		t.Fatalf("stdout=%s", got)
 	}
+	// visible_rule must be forwarded verbatim to the API (transcribe faithfully).
+	var body struct {
+		Questions []map[string]interface{} `json:"questions"`
+	}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("captured body json err=%v body=%s", err, string(stub.CapturedBody))
+	}
+	if len(body.Questions) != 1 {
+		t.Fatalf("questions=%#v", body.Questions)
+	}
+	if _, ok := body.Questions[0]["visible_rule"].(map[string]interface{}); !ok {
+		t.Fatalf("visible_rule not forwarded verbatim: body=%s", string(stub.CapturedBody))
+	}
 }
 
 func TestBaseFormQuestionsExecuteDelete(t *testing.T) {

shortcuts/base/base_form_questions_create.go

@@ -25,14 +25,21 @@ var BaseFormQuestionsCreate = common.Shortcut{
 		{Name: "base-token", Desc: "Base token (base_token)", Required: true},
 		{Name: "table-id", Desc: "table ID", Required: true},
 		{Name: "form-id", Desc: "form ID", Required: true},
-		{Name: "questions", Desc: `questions JSON array, max 10 items. Each item requires "title"(field title) and "type"(text/number/select/datetime/user/attachment/location). Optional fields: "description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown/1=vertical/2=horizontal,select only),"multiple"(bool,select/user),"options"([{"name":"opt","hue":"Blue"}],select only),"style"({"type":"plain/phone/url/email/barcode/rating","precision":2,"format":"yyyy/MM/dd","icon":"star","min":1,"max":5}). E.g. '[{"type":"text","title":"Your name","required":true}]'`, Required: true},
+		{Name: "questions", Desc: `questions JSON array, max 10 items. Each item requires "title"(field title) and "type"(text/number/select/datetime/user/attachment/location). Optional fields: "description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown/1=vertical/2=horizontal,select only),"multiple"(bool,select/user),"options"([{"name":"opt","hue":"Blue"}],select only),"style"({"type":"plain/phone/url/email/barcode/rating","precision":2,"format":"yyyy/MM/dd","icon":"star","min":1,"max":5}),"visible_rule"(display condition; same shape as view filter {"logic":"and","conditions":[["前序题目","==","是"]]}, field references another question's title/id, empty/absent = always shown). E.g. '[{"type":"text","title":"Your name","required":true}]'`, Required: true},
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		return common.NewDryRunAPI().
+		api := common.NewDryRunAPI().
 			POST("/open-apis/base/v3/bases/:base_token/tables/:table_id/forms/:form_id/questions").
 			Set("base_token", runtime.Str("base-token")).
 			Set("table_id", runtime.Str("table-id")).
 			Set("form_id", runtime.Str("form-id"))
+		// Transcribe the questions body verbatim so the preview shows exactly
+		// what would be sent (including optional fields like visible_rule).
+		var questions []interface{}
+		if err := json.Unmarshal([]byte(runtime.Str("questions")), &questions); err == nil {
+			api.Body(map[string]interface{}{"questions": questions})
+		}
+		return api
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		baseToken := runtime.Str("base-token")

shortcuts/base/base_form_questions_update.go

@@ -25,14 +25,26 @@ var BaseFormQuestionsUpdate = common.Shortcut{
 		{Name: "base-token", Desc: "Base token (base_token)", Required: true},
 		{Name: "table-id", Desc: "table ID", Required: true},
 		{Name: "form-id", Desc: "form ID", Required: true},
-		{Name: "questions", Desc: `questions JSON array, max 10 items, each item must include "id". Supported fields: "id"(required),"title","description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown,1=vertical,2=horizontal,select only). E.g. '[{"id":"q_001","title":"Updated?","required":true}]'`, Required: true},
+		{Name: "questions", Desc: `questions JSON array, max 10 items, each item must include "id". Update uses full question overwrite semantics: omitted/empty fields are written as defaults/empty, so run +form-questions-list first and include existing values you want to keep. Supported fields: "id"(required),"title","description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown,1=vertical,2=horizontal,select only),"visible_rule"(display condition; same shape as view filter {"logic":"and","conditions":[["前序题目","==","是"]]}, field references another question's title/id; pass null or omit to clear). E.g. '[{"id":"q_001","title":"Updated?","required":true}]'`, Required: true},
+	},
+	Tips: []string{
+		"Update uses full question overwrite semantics, not a patch.",
+		"Run +form-questions-list first and include existing title/description/required/option_display_mode/visible_rule values you want to keep.",
+		"Omitted fields reset to defaults; empty strings, null, and empty arrays are written as empty/clear when accepted by the API.",
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		return common.NewDryRunAPI().
+		api := common.NewDryRunAPI().
 			PATCH("/open-apis/base/v3/bases/:base_token/tables/:table_id/forms/:form_id/questions").
 			Set("base_token", runtime.Str("base-token")).
 			Set("table_id", runtime.Str("table-id")).
 			Set("form_id", runtime.Str("form-id"))
+		// Transcribe the questions body verbatim so the preview shows exactly
+		// what would be sent (including optional fields like visible_rule).
+		var questions []interface{}
+		if err := json.Unmarshal([]byte(runtime.Str("questions")), &questions); err == nil {
+			api.Body(map[string]interface{}{"questions": questions})
+		}
+		return api
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		baseToken := runtime.Str("base-token")

shortcuts/base/base_shortcuts_test.go

@@ -783,6 +783,20 @@ func TestBaseJSONExamplesLiveInFlagDescriptions(t *testing.T) {
 				`JSON array of question IDs to delete, max 10 items, e.g. '["q_001","q_002"]'`,
 			},
 		},
+		{
+			name:     "form question create visible_rule",
+			shortcut: BaseFormQuestionsCreate,
+			wantHelp: []string{
+				`"visible_rule"(display condition; same shape as view filter`,
+			},
+		},
+		{
+			name:     "form question update visible_rule",
+			shortcut: BaseFormQuestionsUpdate,
+			wantHelp: []string{
+				`"visible_rule"(display condition; same shape as view filter`,
+			},
+		},
 		{
 			name:     "record search json",
 			shortcut: BaseRecordSearch,
@@ -1028,6 +1042,39 @@ func TestBaseFieldUpdateHelpGuidesAgents(t *testing.T) {
 	}
 }
 
+func TestBaseFormQuestionsUpdateHelpGuidesFullOverwrite(t *testing.T) {
+	parent := &cobra.Command{Use: "base"}
+	BaseFormQuestionsUpdate.Mount(parent, &cmdutil.Factory{})
+	cmd := parent.Commands()[0]
+
+	help := cmd.Flags().FlagUsages()
+	wantHelp := []string{
+		"Update uses full question overwrite semantics",
+		"run +form-questions-list first",
+		"include existing values you want to keep",
+		"pass null or omit to clear",
+	}
+	for _, want := range wantHelp {
+		if !strings.Contains(help, want) {
+			t.Fatalf("flag help missing %q:\n%s", want, help)
+		}
+	}
+
+	tips := strings.Join(cmdutil.GetTips(cmd), "\n")
+	wantTips := []string{
+		"full question overwrite semantics, not a patch",
+		"Run +form-questions-list first",
+		"title/description/required/option_display_mode/visible_rule",
+		"Omitted fields reset to defaults",
+		"empty strings, null, and empty arrays are written as empty/clear",
+	}
+	for _, want := range wantTips {
+		if !strings.Contains(tips, want) {
+			t.Fatalf("tips missing %q:\n%s", want, tips)
+		}
+	}
+}
+
 func TestBaseAttachmentHelpGuidesAgents(t *testing.T) {
 	tests := []struct {
 		name     string

shortcuts/common/drive_media_upload.go

@@ -5,9 +5,11 @@ package common
 
 import (
 	"bytes"
+	"context"
 	"fmt"
 	"io"
 	"net/http"
+	"time"
 
 	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 
@@ -50,6 +52,9 @@ type DriveMediaMultipartUploadConfig struct {
 	ParentType string
 	ParentNode string
 	Extra      string
+	// MinRequestInterval is an optional caller-owned pacing interval between
+	// prepare, part, and finish requests for APIs that disallow concurrency.
+	MinRequestInterval time.Duration
 	// Reader mirrors DriveMediaUploadAllConfig.Reader for chunked uploads.
 	Reader io.Reader
 }
@@ -128,14 +133,34 @@ func UploadDriveMediaMultipartTyped(runtime *RuntimeContext, cfg DriveMediaMulti
 		return "", err
 	}
 	fmt.Fprintf(runtime.IO().ErrOut, "Multipart upload initialized: %d chunks x %s\n", session.BlockNum, FormatSize(session.BlockSize))
+	if err := waitDriveMediaMultipartRequest(runtime.Ctx(), cfg.MinRequestInterval); err != nil {
+		return "", err
+	}
 
 	if err = uploadDriveMediaMultipartPartsTyped(runtime, cfg, session); err != nil {
 		return "", err
 	}
 
+	if err := waitDriveMediaMultipartRequest(runtime.Ctx(), cfg.MinRequestInterval); err != nil {
+		return "", err
+	}
 	return finishDriveMediaMultipartUploadTyped(runtime, session.UploadID, session.BlockNum)
 }
 
+func waitDriveMediaMultipartRequest(ctx context.Context, delay time.Duration) error {
+	if delay <= 0 {
+		return nil
+	}
+	timer := time.NewTimer(delay)
+	defer timer.Stop()
+	select {
+	case <-timer.C:
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
 // prefixDriveMediaUploadProblem prepends the upload action to a typed error's
 // message so callers see which upload step failed. Non-typed errors are
 // returned unchanged.
@@ -206,6 +231,11 @@ func uploadDriveMediaMultipartPartsTyped(runtime *RuntimeContext, cfg DriveMedia
 	// Follow the server-declared block plan exactly; upload_finish expects the
 	// same block count returned by upload_prepare.
 	for seq := 0; seq < session.BlockNum; seq++ {
+		if seq > 0 {
+			if err := waitDriveMediaMultipartRequest(runtime.Ctx(), cfg.MinRequestInterval); err != nil {
+				return err
+			}
+		}
 		chunkSize := session.BlockSize
 		if remaining > 0 && chunkSize > remaining {
 			chunkSize = remaining

shortcuts/doc/doc_media_insert.go

@@ -531,7 +531,7 @@ func resolveDocxDocumentID(runtime *common.RuntimeContext, input string) (string
 	case "docx":
 		return docRef.Token, nil
 	case "doc":
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "docs +media-insert only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx").WithParam("--doc")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "this document operation only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx").WithParam("--doc")
 	case "wiki":
 		fmt.Fprintf(runtime.IO().ErrOut, "Resolving wiki node: %s\n", common.MaskToken(docRef.Token))
 		data, err := runtime.CallAPITyped(
@@ -551,13 +551,13 @@ func resolveDocxDocumentID(runtime *common.RuntimeContext, input string) (string
 			return "", errs.NewInternalError(errs.SubtypeInvalidResponse, "wiki get_node returned incomplete node data")
 		}
 		if objType != "docx" {
-			return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "wiki resolved to %q, but docs +media-insert only supports docx documents", objType).WithParam("--doc")
+			return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "wiki resolved to %q, but this document operation only supports docx documents", objType).WithParam("--doc")
 		}
 
 		fmt.Fprintf(runtime.IO().ErrOut, "Resolved wiki to docx: %s\n", common.MaskToken(objToken))
 		return objToken, nil
 	default:
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "docs +media-insert only supports docx documents").WithParam("--doc")
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "this document operation only supports docx documents").WithParam("--doc")
 	}
 }
 

shortcuts/doc/doc_media_upload.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"io"
 	"path/filepath"
+	"time"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
@@ -138,6 +139,9 @@ type UploadDocMediaFileConfig struct {
 	ParentType string
 	ParentNode string
 	DocID      string
+	// MinRequestInterval serializes the prepare/part/finish requests of a
+	// multipart upload. Zero preserves the generic uploader's existing behavior.
+	MinRequestInterval time.Duration
 }
 
 func uploadDocMediaFile(runtime *common.RuntimeContext, cfg UploadDocMediaFileConfig) (string, error) {
@@ -164,13 +168,14 @@ func uploadDocMediaFile(runtime *common.RuntimeContext, cfg UploadDocMediaFileCo
 		})
 	}
 	return common.UploadDriveMediaMultipartTyped(runtime, common.DriveMediaMultipartUploadConfig{
-		FilePath:   cfg.FilePath,
-		Reader:     cfg.Reader,
-		FileName:   cfg.FileName,
-		FileSize:   cfg.FileSize,
-		ParentType: cfg.ParentType,
-		ParentNode: cfg.ParentNode,
-		Extra:      extra,
+		FilePath:           cfg.FilePath,
+		Reader:             cfg.Reader,
+		FileName:           cfg.FileName,
+		FileSize:           cfg.FileSize,
+		ParentType:         cfg.ParentType,
+		ParentNode:         cfg.ParentNode,
+		Extra:              extra,
+		MinRequestInterval: cfg.MinRequestInterval,
 	})
 }
 

shortcuts/doc/docs_create.go

@@ -14,14 +14,21 @@ func v1CreateFlags() []common.Flag {
 	return docsLegacyFlagDefinitions(docsCreateLegacyFlags())
 }
 
+var docsCreateLocalResourceScopes = []string{
+	"docs:document.media:upload",
+	"docx:document:write_only",
+	"docx:document:readonly",
+}
+
 var DocsCreate = common.Shortcut{
-	Service:     "docs",
-	Command:     "+create",
-	Description: "Create a Lark document",
-	Risk:        "write",
-	AuthTypes:   []string{"user", "bot"},
-	Scopes:      []string{"docx:document:create"},
-	PostMount:   installDocsShortcutHelp("+create"),
+	Service:           "docs",
+	Command:           "+create",
+	Description:       "Create a Lark document",
+	Risk:              "write",
+	AuthTypes:         []string{"user", "bot"},
+	Scopes:            []string{"docx:document:create"},
+	ConditionalScopes: docsCreateLocalResourceScopes,
+	PostMount:         installDocsShortcutHelp("+create"),
 	Flags: concatFlags(
 		[]common.Flag{
 			docsAPIVersionCompatFlag(),

shortcuts/doc/docs_create_v2.go

@@ -46,14 +46,19 @@ func validateCreateV2(_ context.Context, runtime *common.RuntimeContext) error {
 		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content is required unless --title is provided").WithParam("--content")
 	}
 	if runtime.Str("content") != "" {
-		_, err := resolveDocsV2ContentReferenceMap(runtime)
-		return err
+		input, err := resolveDocsV2ContentReferenceMap(runtime)
+		if err != nil {
+			return err
+		}
+		if len(input.LocalResources) > 0 {
+			return runtime.EnsureScopes(docsCreateLocalResourceScopes)
+		}
 	}
 	return nil
 }
 
 func dryRunCreateV2(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-	body, err := buildCreateBodyWithHTML5ReferenceMap(runtime)
+	body, resources, err := buildCreateBodyWithPreparedInput(runtime)
 	if err != nil {
 		return common.NewDryRunAPI().Set("error", err.Error())
 	}
@@ -61,14 +66,15 @@ func dryRunCreateV2(_ context.Context, runtime *common.RuntimeContext) *common.D
 	if runtime.IsBot() {
 		desc += ". After document creation succeeds in bot mode, the CLI will also try to grant the current CLI user full_access on the new document."
 	}
-	return common.NewDryRunAPI().
+	dry := common.NewDryRunAPI().
 		POST("/open-apis/docs_ai/v1/documents").
 		Desc(desc).
 		Body(body)
+	return appendLocalDocResourcesDryRun(dry, "<created_document_id>", resources)
 }
 
 func executeCreateV2(_ context.Context, runtime *common.RuntimeContext) error {
-	body, err := buildCreateBodyWithHTML5ReferenceMap(runtime)
+	body, resources, err := buildCreateBodyWithPreparedInput(runtime)
 	if err != nil {
 		return err
 	}
@@ -80,6 +86,12 @@ func executeCreateV2(_ context.Context, runtime *common.RuntimeContext) error {
 
 	augmentDocsCreatePermission(runtime, data)
 	fallbackDocsCreateURLV2(runtime, data)
+	if len(resources) > 0 {
+		doc, _ := data["document"].(map[string]interface{})
+		if err := finalizeLocalDocResources(runtime, strings.TrimSpace(common.GetString(doc, "document_id")), data, resources); err != nil {
+			return err
+		}
+	}
 	runtime.OutRaw(data, nil)
 	return nil
 }

shortcuts/doc/docs_update.go

@@ -14,14 +14,31 @@ func v1UpdateFlags() []common.Flag {
 	return docsLegacyFlagDefinitions(docsUpdateLegacyFlags())
 }
 
+var docsUpdateLocalResourceScopes = []string{
+	"docs:document.media:upload",
+}
+
+var docsUpdateWikiLocalResourceScopes = []string{
+	"docs:document.media:upload",
+	"wiki:node:retrieve",
+}
+
+func docsUpdateLocalResourceScopesFor(ref documentRef) []string {
+	if ref.Kind == "wiki" {
+		return docsUpdateWikiLocalResourceScopes
+	}
+	return docsUpdateLocalResourceScopes
+}
+
 var DocsUpdate = common.Shortcut{
-	Service:     "docs",
-	Command:     "+update",
-	Description: "Update a Lark document",
-	Risk:        "write",
-	Scopes:      []string{"docx:document:write_only", "docx:document:readonly"},
-	AuthTypes:   []string{"user", "bot"},
-	PostMount:   installDocsShortcutHelp("+update"),
+	Service:           "docs",
+	Command:           "+update",
+	Description:       "Update a Lark document",
+	Risk:              "write",
+	Scopes:            []string{"docx:document:write_only", "docx:document:readonly"},
+	ConditionalScopes: docsUpdateWikiLocalResourceScopes,
+	AuthTypes:         []string{"user", "bot"},
+	PostMount:         installDocsShortcutHelp("+update"),
 	Flags: concatFlags(
 		[]common.Flag{
 			docsAPIVersionCompatFlag(),

shortcuts/doc/docs_update_v2.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 
 	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
@@ -50,7 +51,8 @@ func validateUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 	if err := validateDocsV2Only(runtime, "+update", docsUpdateLegacyFlags()); err != nil {
 		return err
 	}
-	if _, err := parseDocumentRef(runtime.Str("doc")); err != nil {
+	docRef, err := parseDocumentRef(runtime.Str("doc"))
+	if err != nil {
 		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --doc: %v", err).WithParam("--doc")
 	}
 	cmd := runtime.Str("command")
@@ -118,8 +120,16 @@ func validateUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 		}
 	}
 	if content != "" {
-		_, err := resolveDocsV2ContentReferenceMap(runtime)
-		return err
+		input, err := resolveDocsV2ContentReferenceMap(runtime)
+		if err != nil {
+			return err
+		}
+		if len(input.LocalResources) > 0 {
+			if err := validateLocalDocResourceUpdateCommand(cmd, input.LocalResources); err != nil {
+				return err
+			}
+			return runtime.EnsureScopes(docsUpdateLocalResourceScopesFor(docRef))
+		}
 	}
 	return nil
 }
@@ -127,32 +137,50 @@ func validateUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 func dryRunUpdateV2(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 	// Validate has already accepted --doc; parseDocumentRef cannot fail here.
 	ref, _ := parseDocumentRef(runtime.Str("doc"))
-	body, err := buildUpdateBodyWithHTML5ReferenceMap(runtime)
+	body, resources, err := buildUpdateBodyWithPreparedInput(runtime)
 	if err != nil {
 		return common.NewDryRunAPI().Set("error", err.Error())
 	}
-	apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s", ref.Token)
-	return common.NewDryRunAPI().
-		PUT(apiPath).
+	documentID := ref.Token
+	dry := common.NewDryRunAPI()
+	if len(resources) > 0 && ref.Kind == "wiki" {
+		documentID = "<resolved_docx_token>"
+		dry.GET("/open-apis/wiki/v2/spaces/get_node").
+			Desc("Resolve wiki node to its docx document before writing local resources").
+			Params(map[string]interface{}{"token": ref.Token})
+	}
+	apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s", validate.EncodePathSegment(documentID))
+	dry.PUT(apiPath).
 		Desc("OpenAPI: update document").
 		Body(body).
-		Set("document_id", ref.Token)
+		Set("document_id", documentID)
+	return appendLocalDocResourcesDryRun(dry, documentID, resources)
 }
 
 func executeUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 	ref, _ := parseDocumentRef(runtime.Str("doc"))
 
-	apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s", ref.Token)
-	body, err := buildUpdateBodyWithHTML5ReferenceMap(runtime)
+	body, resources, err := buildUpdateBodyWithPreparedInput(runtime)
 	if err != nil {
 		return err
 	}
+	documentID := ref.Token
+	if len(resources) > 0 && ref.Kind == "wiki" {
+		documentID, err = resolveDocxDocumentID(runtime, runtime.Str("doc"))
+		if err != nil {
+			return err
+		}
+	}
+	apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s", validate.EncodePathSegment(documentID))
 
 	data, err := doDocAPI(runtime, "PUT", apiPath, body)
 	if err != nil {
 		return err
 	}
 
+	if err := finalizeLocalDocResources(runtime, documentID, data, resources); err != nil {
+		return err
+	}
 	runtime.OutRaw(data, nil)
 	return nil
 }

shortcuts/doc/helpers.go

@@ -76,7 +76,14 @@ func extractDocumentFragment(raw string) string {
 // CallAPITyped lifts the x-tt-logid response header onto the typed error so log_id
 // surfaces for support escalations even when the body omits it.
 func doDocAPI(runtime *common.RuntimeContext, method, apiPath string, body interface{}) (map[string]interface{}, error) {
-	return runtime.CallAPITyped(method, apiPath, nil, body)
+	data, err := runtime.CallAPITyped(method, apiPath, nil, body)
+	if err != nil {
+		return data, err
+	}
+	if data == nil {
+		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "document API returned an empty data object")
+	}
+	return data, nil
 }
 
 func docsSceneFromContext(ctx context.Context) string {

shortcuts/doc/html5_block_resources.go

@@ -49,8 +49,9 @@ type html5BlockReferenceEntry struct {
 type html5BlockReferenceMap map[string]map[string]html5BlockReferenceEntry
 
 type docsV2WriteInput struct {
-	Content      string
-	ReferenceMap map[string]interface{}
+	Content        string
+	ReferenceMap   map[string]interface{}
+	LocalResources []localDocResource
 }
 
 type html5BlockAttr struct {
@@ -68,27 +69,35 @@ type whiteboardStartTag struct {
 	SelfClosing bool
 }
 
-func buildCreateBodyWithHTML5ReferenceMap(runtime *common.RuntimeContext) (map[string]interface{}, error) {
+func buildCreateBodyWithPreparedInput(runtime *common.RuntimeContext) (map[string]interface{}, []localDocResource, error) {
 	body := buildCreateBody(runtime)
 	if runtime.Str("content") == "" && !runtime.Changed("reference-map") {
-		return body, nil
+		return body, nil, nil
 	}
 	input, err := resolveDocsV2ContentReferenceMap(runtime)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
 	}
 	body["content"] = buildCreateContentWithBody(runtime, input.Content)
 	if len(input.ReferenceMap) > 0 {
 		body["reference_map"] = input.ReferenceMap
 	}
-	return body, nil
+	return body, input.LocalResources, nil
 }
 
 func buildUpdateBodyWithHTML5ReferenceMap(runtime *common.RuntimeContext) (map[string]interface{}, error) {
+	body, _, err := buildUpdateBodyWithPreparedInput(runtime)
+	return body, err
+}
+
+func buildUpdateBodyWithPreparedInput(runtime *common.RuntimeContext) (map[string]interface{}, []localDocResource, error) {
 	body := buildUpdateBody(runtime)
 	input, err := resolveDocsV2ContentReferenceMap(runtime)
 	if err != nil {
-		return nil, err
+		return nil, nil, err
+	}
+	if err := validateLocalDocResourceUpdateCommand(runtime.Str("command"), input.LocalResources); err != nil {
+		return nil, nil, err
 	}
 	if input.Content != "" {
 		body["content"] = input.Content
@@ -96,7 +105,7 @@ func buildUpdateBodyWithHTML5ReferenceMap(runtime *common.RuntimeContext) (map[s
 	if len(input.ReferenceMap) > 0 {
 		body["reference_map"] = input.ReferenceMap
 	}
-	return body, nil
+	return body, input.LocalResources, nil
 }
 
 func validateDocsV2ReferenceMapFlags(runtime *common.RuntimeContext) error {
@@ -125,7 +134,11 @@ func prepareDocsV2WriteInput(runtime *common.RuntimeContext, input docsV2WriteIn
 		return docsV2WriteInput{}, err
 	}
 
-	content, err := prepareWhiteboardWriteContent(runtime, runtime.Str("doc-format"), input.Content)
+	content, localResources, err := prepareLocalDocResources(runtime, runtime.Str("doc-format"), input.Content)
+	if err != nil {
+		return docsV2WriteInput{}, err
+	}
+	content, err = prepareWhiteboardWriteContent(runtime, runtime.Str("doc-format"), content)
 	if err != nil {
 		return docsV2WriteInput{}, err
 	}
@@ -138,8 +151,9 @@ func prepareDocsV2WriteInput(runtime *common.RuntimeContext, input docsV2WriteIn
 	}
 	refMap = mergeHTML5ReferenceMap(refMap, html5RefMap)
 	return docsV2WriteInput{
-		Content:      content,
-		ReferenceMap: refMap,
+		Content:        content,
+		ReferenceMap:   refMap,
+		LocalResources: localResources,
 	}, nil
 }
 

skills/lark-base/SKILL.md

@@ -57,12 +57,12 @@ metadata:
 | 写记录 | `+record-upsert` / `+record-batch-create` / `+record-batch-update` | 必读 [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) 和 [lark-base-cell-value.md](references/lark-base-cell-value.md) |
 | 附件字段 | `+record-upload-attachment` / `+record-download-attachment` / `+record-remove-attachment` | 附件不要伪造成普通 CellValue；上传走本地文件，下载/删除按 file token 或字段定位 |
 | 删除记录 / 分享记录链接 / 历史 | `+record-delete` / `+record-share-link-create` / `+record-history-list` | 删除前确认 record；分享链接最多 100 条；历史读 [lark-base-record-history-list.md](references/lark-base-record-history-list.md)，只查单条记录，不做整表审计 |
-| 管理视图 | `+view-*` | `+view-set-filter` 读 [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)；其余配置先 get 现状，再按返回结构更新 |
+| 管理视图 | `+view-*` | `+view-set-filter` 读 [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)（filter 条件结构见公共协议 [lark-base-filter-condition.md](references/lark-base-filter-condition.md)）；其余配置先 get 现状，再按返回结构更新 |
 | 一次性聚合统计 | `+data-query` | 必读 [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md) 和入口 [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md)；完整 DSL 再读 [lark-base-data-query.md](references/lark-base-data-query.md) |
 | 公式字段 | `+field-create/update --json '{"type":"formula",...}'` | 必读 [formula-field-guide.md](references/formula-field-guide.md)，读后再加隐藏确认 flag `--i-have-read-guide` |
 | Lookup 字段 | `+field-create/update --json '{"type":"lookup",...}'` | 必读 [lookup-field-guide.md](references/lookup-field-guide.md)，读后再加隐藏确认 flag `--i-have-read-guide` |
 | 表单提交 | `+form-submit` | 先读 [lark-base-form-detail.md](references/lark-base-form-detail.md) 获取题目、filter 和附件所需 `base_token`；提交 JSON 读 [lark-base-form-submit.md](references/lark-base-form-submit.md) |
-| 表单题目创建/更新 | `+form-questions-create` / `+form-questions-update` | 读 [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md) |
+| 表单题目创建/更新 | `+form-questions-create` / `+form-questions-update` | 读 [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md)；题目显隐条件 `visible_rule` 结构见公共协议 [lark-base-filter-condition.md](references/lark-base-filter-condition.md) |
 | 其他表单管理 | `+form-list/get/detail/create/update/delete` / `+form-questions-list/delete` | `+form-detail` 读 [lark-base-form-detail.md](references/lark-base-form-detail.md)；删除前确认目标表单 |
 | 仪表盘与组件 | `+dashboard-*` / `+dashboard-block-*` | 提到图表/看板/block 时先读 [lark-base-dashboard.md](references/lark-base-dashboard.md)；组件 `data_config` 读 [dashboard-block-data-config.md](references/dashboard-block-data-config.md)；读取图表计算结果用 `+dashboard-block-get-data` |
 | Workflow | `+workflow-*` | 创建/更新或理解 steps 时读入口 [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) 和 steps JSON SSOT [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)；list/get/enable/disable 只处理 workflow ID 与启停状态 |
@@ -116,6 +116,7 @@ metadata:
 ## 表单与视图细节
 
 - `+form-submit` 是高风险写操作，必须带 `--yes` 确认；调用前必须先跑 `+form-detail`，读取 `questions[].type`、`required`、`filter` 和附件场景需要的 `base_token`；不要填写被 filter 隐藏的问题。
+- `+form-questions-update` 是题目配置全量覆盖，不是 patch；未传字段会回落默认值，传空字符串 / `null` / 空数组会直接写入空或清空。更新前先 `+form-questions-list` 读取当前题目，把要保留的 `title` / `description` / `required` / `option_display_mode` / `visible_rule` 等字段带回请求。
 - 表单附件不要写进 `fields`，放在 `--json.attachments`；提交附件时必须同时传表单所属 Base 的 `--base-token`。
 - `+view-set-filter` 是唯一保留的 view reference；sort/group/card/timebar/visible-fields 这类配置先用对应 get 命令读现状，保留未修改字段，只替换用户要求变更的配置。
 - 视图适合持久化、共享和 UI 复用；一次性筛选/排序可先用 `+record-list` / `+record-search` 的 filter/sort 验证结果，再按需要沉淀为持久视图。
@@ -146,13 +147,14 @@ metadata:
 ## 保留 Reference
 
 - [lark-base-data-analysis-sop.md](references/lark-base-data-analysis-sop.md)：查询/统计/全局结论的选路 SOP
-- [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md) / [lark-base-data-query.md](references/lark-base-data-query.md)：聚合查询入口 fewshot 与 DSL SSOT
+- [lark-base-data-query-guide.md](references/lark-base-data-query-guide.md) / [lark-base-data-query.md](references/lark-base-data-query.md)：聚合查询入口 fewshot 与 DSL SSOT；`+data-query` 的 `filters` 结构是独立对象 DSL，不使用公共 tuple filter 协议
 - [lark-base-cell-value.md](references/lark-base-cell-value.md)：记录 CellValue 构造
 - [lark-base-field-json.md](references/lark-base-field-json.md)：字段 JSON 构造
 - [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)：公式与 lookup 字段
 - [lark-base-field-create.md](references/lark-base-field-create.md) / [lark-base-field-update.md](references/lark-base-field-update.md)：字段创建/更新命令级补充
 - [lark-base-record-upsert.md](references/lark-base-record-upsert.md) / [lark-base-record-batch-create.md](references/lark-base-record-batch-create.md) / [lark-base-record-batch-update.md](references/lark-base-record-batch-update.md) / [lark-base-record-history-list.md](references/lark-base-record-history-list.md)：记录写入 JSON 与历史返回解释
 - [lark-base-view-set-filter.md](references/lark-base-view-set-filter.md)：视图筛选 JSON
+- [lark-base-filter-condition.md](references/lark-base-filter-condition.md)：视图 filter、记录 `--filter-json`、表单 `visible_rule` 的 tuple 条件结构公共协议 SSOT；不适用于 `+data-query`
 - [lark-base-form-detail.md](references/lark-base-form-detail.md) / [lark-base-form-submit.md](references/lark-base-form-submit.md) / [lark-base-form-questions-create.md](references/lark-base-form-questions-create.md) / [lark-base-form-questions-update.md](references/lark-base-form-questions-update.md)：表单详情、提交和复杂 JSON
 - [lark-base-dashboard.md](references/lark-base-dashboard.md) / [dashboard-block-data-config.md](references/dashboard-block-data-config.md) / [lark-base-dashboard-block-get-data.md](references/lark-base-dashboard-block-get-data.md)：仪表盘、组件配置与图表结果协议
 - [lark-base-workflow-guide.md](references/lark-base-workflow-guide.md) / [lark-base-workflow-schema.md](references/lark-base-workflow-schema.md)：workflow 入口与 steps JSON SSOT

skills/lark-base/references/lark-base-filter-condition.md

@@ -0,0 +1,179 @@
+# Base Filter 条件结构（公共协议）
+
+Filter 是一组「字段/操作符/值」条件的组合，用 `logic`（`and` / `or`）把多条 `conditions` 连接起来，用于描述「满足什么条件」。视图筛选 `filter`、记录读取/搜索的 `--filter-json`、表单题目显隐条件 `visible_rule` 复用同一套 tuple 结构，本文件是其公共协议（SSOT）。
+
+## 0. 适用范围
+
+本协议只适用于以下场景：
+
+- `+view-set-filter` / `+view-get-filter` 的视图筛选配置。
+- `+record-list --filter-json` / `+record-search --filter-json` 的结构化记录筛选。
+- `+form-questions-create` / `+form-questions-update` 中的 `visible_rule` 显隐条件。
+
+本协议**不适用于 `+data-query`**。`+data-query` 支持过滤，但使用的是 LiteQuery DSL 的 `filters` 对象结构：`{"type":1,"conjunction":"and","conditions":[{"field_name":"状态","operator":"is","value":["有效"]}]}`，不是这里的 tuple 条件 `["状态","==","有效"]`。构造 `+data-query --dsl` 时请阅读 [lark-base-data-query.md](lark-base-data-query.md) 的 FilterGroup / Condition 章节。
+
+## 1. 顶层结构
+
+- 必须是 JSON 对象。
+- 顶层结构是 `{logic?, conditions?}`。
+- `logic` 默认 `and`；推荐只用 canonical 值 `and` / `or`。
+- `conditions` 默认空数组。
+- 每条条件写成 tuple：`[field, operator, value?]`。
+- `empty` / `non_empty` 可写成 2 项：`[field, "empty"]`、`[field, "non_empty"]`。
+
+```json
+{
+  "logic": "and",
+  "conditions": [
+    ["状态", "intersects", ["Doing"]],
+    ["负责人", "intersects", [{ "id": "ou_xxx" }]],
+    ["截止时间", "empty"]
+  ]
+}
+```
+
+清空写法：
+
+```json
+{
+  "conditions": []
+}
+```
+
+## 2. operator
+
+可用 operator：
+- `==`
+- `!=`
+- `>`
+- `>=`
+- `<`
+- `<=`
+- `intersects`
+- `disjoint`
+- `empty`
+- `non_empty`
+
+## 3. value 写法
+
+value 类型取决于条件引用对象（字段 / 题目）的类型。
+
+### `text`
+
+用字符串：
+
+```json
+["标题", "intersects", "发布"]
+```
+
+### `location`
+
+location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度筛选；优先使用 `intersects` 做包含匹配，例如查深圳：
+
+```json
+["位置", "intersects", "深圳"]
+```
+
+不推荐写 `["位置", "==", "深圳"]` 这类精确匹配，除非确保筛选值与完整 `full_address` 完全一致。
+
+### `number` / `auto_number`
+
+用数字：
+
+```json
+["工时", ">=", 3.5]
+```
+
+### `select`
+
+用选项名数组：
+
+```json
+["状态", "intersects", ["Doing", "Blocked"]]
+```
+
+### `user` / `created_by` / `updated_by`
+
+用对象数组：
+
+> **人员筛选：不要猜 ID。** 不知道 `open_id` 时，先用 `lark-contact` 查 id：`lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user`。
+
+```json
+["负责人", "intersects", [{ "id": "ou_xxx" }]]
+```
+
+### `group_chat`
+
+用对象数组：
+
+> **群组筛选：不要猜 ID。** 不知道 `chat_id` 时，先用 `lark-im` 搜群：`lark-cli im +chat-search --query "<群名关键词>" --as user`；取结果里的 `oc_xxx`。
+
+```json
+["负责群", "intersects", [{ "id": "oc_xxx" }]]
+```
+
+### `link`
+
+用记录 id 对象数组：
+
+```json
+["关联任务", "intersects", [{ "id": "rec_xxx" }]]
+```
+
+### `checkbox`
+
+用布尔值：
+
+```json
+["完成", "==", true]
+```
+
+### `datetime` / `created_at` / `updated_at`
+
+用相对时间关键字或 `ExactDate(...)`：
+
+```json
+["截止时间", "==", "ExactDate(2026-01-01)"]
+```
+
+```json
+["截止时间", "==", "ExactDate(2026-01-01 11:30)"]
+```
+
+```json
+["截止时间", "==", "Today"]
+```
+
+可用关键字：
+- `Today`
+- `Yesterday`
+- `Tomorrow`
+
+### `formula` / `lookup`
+
+- 筛选值类型由字段计算结果类型动态决定。
+- 拿不准时，先把 `value` 当作单个字符串填入做一次尝试。
+- 如果报错，再按错误提示把 `value` 改成对应类型。
+
+字符串示例：
+
+```json
+["风险说明", "intersects", "高风险"]
+```
+
+数字示例：
+
+```json
+["汇总分", ">=", 80]
+```
+
+## 4. 易错点
+
+- 不要再写旧对象风格：`{"field_name":...,"operator":...}`。
+- `user` / `group_chat` / `link` 不要写成单个标量。
+- `empty` / `non_empty` 不要硬塞无意义的 value。
+- 日期条件稳定写法用 `ExactDate(...)` 或 `Today` / `Yesterday` / `Tomorrow`。
+- `formula` / `lookup` 的 value 形状不固定；拿不准时先读当前配置或字段定义，或根据错误提示修正类型。
+
+## 5. 参考
+- [lookup-field-guide.md](lookup-field-guide.md)

skills/lark-base/references/lark-base-form-questions-create.md

@@ -19,10 +19,7 @@ lark-cli base +form-questions-create \
   --base-token <base_token> \
   --table-id <table_id> \
   --form-id <form_id> \
-  --questions '[
-    {"type":"text","title":"您的姓名是？","required":true},
-    {"type":"text","title":"您的联系方式是？","required":false}
-  ]'
+  --questions '[{"type":"text","title":"您的姓名是？","required":true},{"type":"text","title":"您的联系方式是？","required":false}]'
 
 # 添加单选题（带选项）
 lark-cli base +form-questions-create \
@@ -50,6 +47,13 @@ lark-cli base +form-questions-create \
   --table-id <table_id> \
   --form-id <form_id> \
   --questions '[{"type":"text","title":"反馈建议","description":"更多详情请查看[帮助文档](https://example.com/help)"}]'  
+
+# 添加带显隐条件（visible_rule）的问题：当「是否需要发票」选择「是」时才显示「发票抬头」
+lark-cli base +form-questions-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"type":"select","title":"是否需要发票","required":true,"options":[{"name":"是","hue":"Blue"},{"name":"否","hue":"Gray"}]},{"type":"text","title":"发票抬头","visible_rule":{"logic":"and","conditions":[["是否需要发票","==","是"]]}}]'
 ```
 
 ## 参数
@@ -78,6 +82,7 @@ lark-cli base +form-questions-create \
 | `multiple`            | 否 | 是否多选（`select`/`user` 类型有效，bool） |
 | `options`             | 否 | 选项列表（仅 `select` 有效）：`[{"name":"选项1","hue":"Blue"}]`，hue 可选：`Red`/`Orange`/`Yellow`/`Green`/`Blue`/`Purple`/`Gray` |
 | `style`               | 否 | 字段样式配置（见下方说明） |
+| `visible_rule`        | 否 | 题目显隐条件（见下方「`visible_rule` 显隐条件」） |
 
 ### `style` 字段说明
 
@@ -88,6 +93,30 @@ lark-cli base +form-questions-create \
 | `number`（评分） | `{"type":"rating","icon":"star","min":1,"max":5}` | icon 可选：`star`/`heart`/`thumbsup`/`fire`/`smile`/`lightning`/`flower`/`number` |
 | `datetime` | `{"format":"yyyy/MM/dd"}` | format 可选：`yyyy/MM/dd`、`yyyy/MM/dd HH:mm`、`MM-dd`、`MM/dd/yyyy`、`dd/MM/yyyy` |
 
+### `visible_rule` 显隐条件
+
+> **仅当用户明确要求为题目设置显隐条件（显示/隐藏逻辑）时，才需要读下面的结构说明；否则忽略本节。**
+
+`visible_rule` 控制题目在表单中的显示/隐藏：当条件满足时题目显示，不满足时隐藏；不传或 `conditions` 为空数组则题目始终显示。
+
+- **结构与视图筛选 `filter` 完全一致**，即 `{logic?, conditions?}`，共用同一套公共协议。
+- 与视图 `filter` 唯一的区别：`conditions` 中的 `field` 引用的是**同一表单内其他题目的题目名称或题目 ID**（推荐用题目 ID 以避免重名歧义），而不是数据表字段。
+- **只能引用前序题目**：条件只能引用排在当前题目之前的题目——创建时按 `questions` 数组顺序判定（可引用同批次更靠前的新题目或表单中已有题目），不支持循环引用。
+- 引用的题目必须真实存在，否则会报错。
+- 列出题目（`+form-questions-list`）会在每个题目对象中**原样返回** `visible_rule`；未设置显隐条件的题目返回 `null` 或 `conditions` 为空数组。
+
+```json
+{
+  "logic": "and",
+  "conditions": [
+    ["是否需要发票", "==", "是"],
+    ["报销金额", ">=", 1000]
+  ]
+}
+```
+
+详细的 `visible_rule` 结构（顶层规则、operator 列表、各题目类型的 value 写法）请阅读 [lark-base-filter-condition.md](lark-base-filter-condition.md)。
+
 ## 输出格式
 
 返回创建成功的问题列表：
@@ -115,4 +144,5 @@ lark-cli base +form-questions-create \
 ## 参考
 
 - [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-base-filter-condition.md](lark-base-filter-condition.md) — `visible_rule` / `filter` 条件结构公共协议
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-base/references/lark-base-form-questions-update.md

@@ -2,40 +2,60 @@
 
 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
 
-批量更新多维表格表单/问卷中的问题（标题、描述、是否必填）。
+批量更新多维表格表单/问卷中的问题配置（标题、描述、是否必填、显隐条件等）。
+
+> [!CAUTION]
+> `+form-questions-update` 是**题目配置全量覆盖**，不是 patch。对每个传入的题目，未携带的属性会回落为默认值，显式传空字符串 / `null` / 空数组会直接写入空或清空；如果要保留现有属性，必须先用 `+form-questions-list` 查出现状，再把要保留的字段一起带回 `--questions`。
 
 ## 命令
 
 ```bash
-# 更新一个问题的标题
-lark-cli base +form-questions-update \
+# 先读取现有题目配置，作为 read-modify-write 的基线
+lark-cli base +form-questions-list \
   --base-token <base_token> \
   --table-id <table_id> \
-  --form-id <form_id> \
-  --questions '[{"id":"q_001","title":"您的真实姓名是？"}]'
+  --form-id <form_id>
 
-# 同时更新多个问题
+# 更新一个问题的标题，同时带回要保留的 required / description / visible_rule 等字段
 lark-cli base +form-questions-update \
   --base-token <base_token> \
   --table-id <table_id> \
   --form-id <form_id> \
-  --questions '[
-    {"id":"q_001","title":"姓名（必填）","required":true},
-    {"id":"q_002","title":"联系方式","required":false}
-  ]'
+  --questions '[{"id":"q_001","title":"您的真实姓名是？","description":"请填写真实姓名","required":true,"visible_rule":null}]'
+
+# 同时更新多个问题；每个对象都应是该题目的目标完整配置
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_001","title":"姓名（必填）","required":true},{"id":"q_002","title":"联系方式","required":false}]'
   
-# 更新问题描述（纯文本）
+# 更新问题描述（纯文本），同时带回要保留的 title / required / visible_rule
 lark-cli base +form-questions-update \
   --base-token <base_token> \
   --table-id <table_id> \
   --form-id <form_id> \
-  --questions '[{"id":"q_001","description":"请填写您的真实姓名"}]'
-# 更新问题描述（含链接）
+  --questions '[{"id":"q_001","title":"您的姓名","description":"请填写您的真实姓名","required":true,"visible_rule":null}]'
+# 更新问题描述（含链接），同时带回要保留的 title / required / visible_rule
 lark-cli base +form-questions-update \
   --base-token <base_token> \
   --table-id <table_id> \
   --form-id <form_id> \
-  --questions '[{"id":"q_001","description":"更多说明请参考[帮助文档](https://example.com/help)"}]'  
+  --questions '[{"id":"q_001","title":"反馈建议","description":"更多说明请参考[帮助文档](https://example.com/help)","required":false,"visible_rule":null}]'
+
+# 更新题目显隐条件（visible_rule），同时带回要保留的 title / description / required
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_002","title":"发票抬头","description":"","required":false,"visible_rule":{"logic":"and","conditions":[["q_001","==","是"]]}}]'
+
+# 清空题目显隐条件（使题目始终显示），同时带回要保留的 title / description / required
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_002","title":"发票抬头","description":"","required":false,"visible_rule":null}]'
 ```
 
 ## 参数
@@ -52,15 +72,46 @@ lark-cli base +form-questions-update \
 
 ## `--questions` 格式
 
-每个问题对象必须包含 `id`，其余字段按需传入：
+每个问题对象必须包含 `id`。注意：对象不是增量 patch，而是该题目的目标完整配置；未携带字段会按服务端默认值重建。
 
 | 字段 | 必填 | 说明 |
 |------|------|------|
 | `id` | **是** | 问题 ID（field_id），不可修改 |
-| `title` | 否 | 新的问题标题 |
-| `description` | 否 | 新的问题描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`） |
-| `required` | 否 | 是否必填 |
-| `option_display_mode` | 否 | 选项展示方式（仅 `select` 有效）：`0`=下拉，`1`=纵向（默认），`2`=横向 |
+| `title` | 否 | 目标问题标题；省略会回落为字段名，传空字符串会写入空标题（若服务端允许） |
+| `description` | 否 | 目标问题描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`）；省略或传空字符串都会清空描述 |
+| `required` | 否 | 目标是否必填；省略会回落为 `false` |
+| `option_display_mode` | 否 | 目标选项展示方式（仅 `select` 有效）：`0`=下拉，`1`=纵向（默认），`2`=横向；省略会回落默认展示方式 |
+| `visible_rule` | 否 | 目标题目显隐条件；传完整 `{logic, conditions}` 对象覆盖，传 `null` 或省略都会清空（见下方说明） |
+
+## 全量覆盖语义
+
+- 先执行 `+form-questions-list`，读取被更新题目的当前 `id`、`title`、`description`、`required`、`option_display_mode`、`visible_rule`。
+- 构造 `--questions` 时，只改用户明确要求变化的字段；所有仍要保留的字段必须按当前值一并传回。
+- 不要用“只传要改的字段”的方式更新题目。比如只传 `{"id":"q_002","title":"新标题"}` 会让 `description` 清空、`required` 回落为 `false`、`visible_rule` 清空。
+- 用户明确要求清空时才传空值：`description:""` 清空描述，`visible_rule:null` 清空显隐条件，`conditions:[]` 也表示无条件显示。
+
+### `visible_rule` 显隐条件
+
+> **仅当用户明确要求为题目设置或修改显隐条件（显示/隐藏逻辑）时，才需要读下面的结构说明；否则忽略本节。**
+
+`visible_rule` 控制题目显示/隐藏，**结构与视图筛选 `filter` 完全一致**（`{logic?, conditions?}`），共用同一套公共协议。
+
+- `conditions` 中的 `field` 引用**同一表单内其他题目的题目名称或题目 ID**（推荐用题目 ID）。
+- 更新时按表单中题目的**实际顺序**判定，只能引用排在当前题目之前的题目；不支持循环引用。
+- 更新 `visible_rule` 需传**完整**的 `{logic, conditions}` 对象（整体覆盖）；要保留现有显隐条件就必须把当前 `visible_rule` 原样带回；传 `null`、省略 `visible_rule` 或传空 `conditions` 都会使题目始终显示。
+- 列出题目（`+form-questions-list`）会在每个题目对象中**原样返回** `visible_rule`；未设置显隐条件的题目返回 `null` 或 `conditions` 为空数组。
+
+```json
+{
+  "logic": "and",
+  "conditions": [
+    ["q_001", "==", "是"],
+    ["q_003", ">=", 1000]
+  ]
+}
+```
+
+详细的 `visible_rule` 结构（顶层规则、operator 列表、各题目类型的 value 写法）请阅读 [lark-base-filter-condition.md](lark-base-filter-condition.md)。
 
 ## 输出格式
 
@@ -82,11 +133,13 @@ lark-cli base +form-questions-update \
 > [!CAUTION]
 > 这是**写入操作** — 执行前必须向用户确认。
 
-1. 先用 `+form-questions-list` 获取现有问题及其 `id`
-2. 构造包含 `id` 的更新数组
-3. 执行命令并报告更新结果
+1. 先用 `+form-questions-list` 获取现有问题及其 `id` 和完整配置。
+2. 以现有配置为基线，只修改用户明确要求变化的字段；要保留的字段必须原样带回。
+3. 构造包含 `id` 和目标完整配置的更新数组。
+4. 执行命令并报告更新结果。
 
 ## 参考
 
 - [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-base-filter-condition.md](lark-base-filter-condition.md) — `visible_rule` / `filter` 条件结构公共协议
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-base/references/lark-base-view-set-filter.md

@@ -4,142 +4,13 @@
 
 更新视图筛选配置。
 
-## 1. 顶层规则
+## 1. filter 结构
+
+`--json` 就是一个 filter 条件对象，结构见公共协议 SSOT [lark-base-filter-condition.md](lark-base-filter-condition.md)，即 `{logic?, conditions?}`。此处 `conditions` 中的 `field` 引用**数据表字段名或字段 id**。
 
-- `--json` 必须是 JSON 对象。
-- 顶层结构是 `{logic?, conditions?}`。
-- `logic` 默认 `and`；推荐只用 canonical 值 `and` / `or`。
-- `conditions` 默认空数组。
-- 每条条件写成 tuple：`[field, operator, value?]`。
-- `empty` / `non_empty` 可写成 2 项：`[field, "empty"]`、`[field, "non_empty"]`。
 - 支持 `filter` 的视图类型：`grid`、`kanban`、`gallery`、`calendar`、`gantt`。
 
-## 2. operator
-
-可用 operator：
-- `==`
-- `!=`
-- `>`
-- `>=`
-- `<`
-- `<=`
-- `intersects`
-- `disjoint`
-- `empty`
-- `non_empty`
-
-## 3. value 写法
-
-### `text`
-
-用字符串：
-
-```json
-["标题", "intersects", "发布"]
-```
-
-### `location`
-
-location 筛选只按 `full_address` 字符串匹配，不能直接按经纬度筛选；优先使用 `intersects` 做包含匹配，例如查深圳：
-
-```json
-["位置", "intersects", "深圳"]
-```
-
-不推荐写 `["位置", "==", "深圳"]` 这类精确匹配，除非确保筛选值与完整 `full_address` 完全一致。
-
-### `number` / `auto_number`
-
-用数字：
-
-```json
-["工时", ">=", 3.5]
-```
-
-### `select`
-
-用选项名数组：
-
-```json
-["状态", "intersects", ["Doing", "Blocked"]]
-```
-
-### `user` / `created_by` / `updated_by`
-
-用对象数组：
-
-> **人员筛选：不要猜 ID。** 不知道 `open_id` 时，先用 `lark-contact` 查 id：`lark-cli contact +search-user --query "<姓名/邮箱/手机号>" --as user`。
-
-```json
-["负责人", "intersects", [{ "id": "ou_xxx" }]]
-```
-
-### `group_chat`
-
-用对象数组：
-
-> **群组筛选：不要猜 ID。** 不知道 `chat_id` 时，先用 `lark-im` 搜群：`lark-cli im +chat-search --query "<群名关键词>" --as user`；取结果里的 `oc_xxx`。
-
-```json
-["负责群", "intersects", [{ "id": "oc_xxx" }]]
-```
-
-### `link`
-
-用记录 id 对象数组：
-
-```json
-["关联任务", "intersects", [{ "id": "rec_xxx" }]]
-```
-
-### `checkbox`
-
-用布尔值：
-
-```json
-["完成", "==", true]
-```
-
-### `datetime` / `created_at` / `updated_at`
-
-用相对时间关键字或 `ExactDate(...)`：
-
-```json
-["截止时间", "==", "ExactDate(2026-01-01)"]
-```
-
-```json
-["截止时间", "==", "ExactDate(2026-01-01 11:30)"]
-```
-
-```json
-["截止时间", "==", "Today"]
-```
-
-可用关键字：
-- `Today`
-- `Yesterday`
-- `Tomorrow`
-
-### `formula` / `lookup`
-
-- 筛选值类型由字段计算结果类型动态决定。
-- 拿不准时，先把 `value` 当作单个字符串填入做一次尝试。
-- 如果报错，再按错误提示把 `value` 改成对应类型。
-
-字符串示例：
-
-```json
-["风险说明", "intersects", "高风险"]
-```
-
-数字示例：
-
-```json
-["汇总分", ">=", 80]
-```
-
-## 4. 推荐命令
+## 2. 推荐命令
 
 ```bash
 lark-cli base +view-set-filter \
@@ -149,7 +20,7 @@ lark-cli base +view-set-filter \
   --json '{"logic":"and","conditions":[["状态","intersects",["Doing"]],["负责人","intersects",[{"id":"ou_xxx"}]],["截止时间","empty"]]}'
 ```
 
-## 5. JSON 写法
+## 3. JSON 写法
 
 ```json
 {
@@ -170,14 +41,16 @@ lark-cli base +view-set-filter \
 }
 ```
 
-## 6. 使用建议
+完整的 operator 列表与各字段类型的 value 写法（`text` / `number` / `select` / `user` / `datetime` / `formula` / `lookup` 等），见 [lark-base-filter-condition.md](lark-base-filter-condition.md)。
+
+## 4. 使用建议
 
 - 先读取当前筛选配置，理解现有 `logic` 和 `conditions` 的组合关系；只替换用户要求变更的条件，未提到的条件默认保留。
 - 优先传字段 id，不要依赖字段名。
 - 拿不准字段 type 或真实取值时，先用 `+field-list` / `+record-list` 确认，再按对应字段类型的 value 写法构造条件；别按字段名猜 type、凭印象猜枚举取值。
 - 需要清空全部筛选时，直接传 `{"conditions":[]}`。
 
-## 7. 易错点
+## 5. 易错点
 
 - 本 tuple DSL 由 `+view-set-filter` 与 `+record-list` / `+record-search` 的 `--filter-json` 共用；不要写成 `+data-query` 的对象风格 `{"field_name":...,"operator":...}`（会报校验失败）。
 - 标量类字段（`text` / `number` / `datetime` 等）的 value 用标量、别包成数组（各类型详见 value 写法一节）。
@@ -186,6 +59,7 @@ lark-cli base +view-set-filter \
 - 日期条件稳定写法用 `ExactDate(...)` 或 `Today` / `Yesterday` / `Tomorrow`。
 - `formula` / `lookup` 的 value 形状不固定；拿不准时先读当前 filter 或字段定义，或根据错误提示修正类型。
 
-## 8. 参考
+## 6. 参考
 
+- [lark-base-filter-condition.md](lark-base-filter-condition.md)：filter/visible_rule 条件结构公共协议 SSOT
 - [lookup-field-guide.md](lookup-field-guide.md)

skills/lark-calendar/SKILL.md

@@ -201,4 +201,4 @@ lark-cli im +chat-search --query <query> --as user
 - 会议室物理设施管理 → 管理员后台
 
 **注意（强制性）：**
-- 涉及日期（时间）字符串与时间戳的相互转换时，务必调用系统命令或脚本代码等外部工具进行处理，以确保转换的绝对准确。违者将导致严重的逻辑错误！
+- 涉及日期（时间）字符串与时间戳的相互转换时，务必调用系统命令或脚本代码等外部工具进行处理，以确保转换的绝对准确；换算**禁止依赖容器默认时区**（常为 UTC，会导致 8 小时偏移），必须显式指定目标时区。违者将导致严重的逻辑错误！

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

@@ -30,8 +30,8 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--summary <text>` | 否 | 日程标题。注意：标题中不应该出现时间、地点、人物信息 |
-| `--start <time>` | 是 | 开始时间（ISO 8601，如 `2026-03-12T14:00+08:00`） |
-| `--end <time>` | 是 | 结束时间（ISO 8601） |
+| `--start <time>` | 是 | 开始时间（ISO 8601，**必须带时区偏移**，如 `2026-03-12T14:00+08:00`；不带偏移会按进程时区解析致偏移） |
+| `--end <time>` | 是 | 结束时间（ISO 8601，**必须带时区偏移**） |
 | `--description <markdown>` | 否 | 日程描述，统一使用此字段，格式为 **Markdown**。提供会议议程、活动内容、注意事项或链接等。支持加粗、斜体、下划线（`<u>...</u>`）、删除线、链接 `[文本](url)`、标题（`# ` 到 `### `，最多三级）、引用（`> `）、有序/无序列表、GFM 表格（`\| 列1 \| 列2 \|` + 分隔行 `\| --- \| --- \|`）、以及图片 `![图片名](图片URL)`（标准 Markdown 图片语法：远程 URL 原样使用；**本地图片路径**（相对路径、且位于当前工作目录内）会自动上传到云盘并在端上内联渲染——绝对路径或工作目录之外的路径会报错；端上已有图片读回为 Markdown 图片）。飞书文档 URL（直接粘贴裸链接，或写成 `[文本](url)`）会自动解析为内联文档，端上展示文档标题而非裸链接。支持 `@文件路径` 或 `-`（stdin）读取。**禁止**用 `***文本***` 同时表示加粗+斜体（端上会残留 `*`）；应嵌套书写，如 `**<u>*~~文本~~*</u>**` 或 `*<u>**~~文本~~**</u>*`。|
 | `--attendee-ids <id_list>` | 否 | 参与人 ID 列表（逗号分隔）。支持用户（`ou_`）、群组（`oc_`）和会议室（`omm_`）。AI 提取时请务必保留对应前缀。bot 可作为合法参会人，无需剔除 |
 | `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） |
@@ -61,7 +61,7 @@ lark-cli calendar event.attendees create \
   --data '{"attendees": [{"type": "resource", "room_id": "omm_xxx", "approval_reason": "申请原因"}]}'
 
 完整 API 命令的关键差异：
-- 时间参数是 **Unix 秒字符串**（非 ISO 8601）。
+- 时间参数是 **Unix 秒字符串**（非 ISO 8601）。换算时**禁止依赖容器默认时区**（常为 UTC，会导致 8 小时偏移），必须显式指定目标时区。
 - 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天；单日全天日程两者相同。
 - 手动拆成“创建日程 + 添加参会人”两步时，若第二步失败，建议删除刚创建的空日程，避免遗留无参会人的日程。
 - 设置会议 owner：`+create` 不支持，需用完整 API 命令在 `vchat.meeting_settings.owner_id` 中设置，且必须同时设置 `vchat.vc_type` 为 `vc`（代表该日程为 VC 视频会议）。仅当以应用（bot）身份在应用日历上操作时生效；owner 必须为用户身份（`ou_` open_id），不能为非用户或外部租户用户。

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

@@ -44,8 +44,8 @@ lark-cli calendar +update \
 | `--calendar-id <id>` | 否 | 日历 ID（省略则使用 `primary`） |
 | `--summary <text>` | 否 | 新日程标题。仅在显式传入 `--summary` 时更新；若传空字符串，会把标题清空 |
 | `--description <markdown>` | 否 | 新日程描述，统一使用此字段，格式为 **Markdown**（加粗、斜体、下划线 `<u>...</u>`、删除线、链接 `[文本](url)`、标题 `# `~`### `（最多三级）、引用 `> `、有序/无序列表、GFM 表格 `\| 列1 \| 列2 \|` + 分隔行 `\| --- \| --- \|`、以及图片 `![图片名](图片URL)`（标准 Markdown 图片语法：远程 URL 原样使用；**本地图片路径**（相对路径、且位于当前工作目录内）会自动上传到云盘并在端上内联渲染——绝对路径或工作目录之外的路径会报错；端上已有图片读回为 Markdown 图片）。飞书文档 URL（裸链接或 `[文本](url)`）会自动解析为内联文档，端上展示文档标题。支持 `@文件路径` 或 `-`（stdin）读取。仅在显式传入时更新；传空字符串 `""` 会清空描述。**禁止**用 `***文本***` 同时表示加粗+斜体（端上会残留 `*`）；应嵌套书写，如 `**<u>*~~文本~~*</u>**` 或 `*<u>**~~文本~~**</u>*`。 |
-| `--start <time>` | 否 | 新开始时间（ISO 8601，如 `2026-03-12T14:00+08:00`）。更新日程时间时必须同时传 `--end` |
-| `--end <time>` | 否 | 新结束时间（ISO 8601）。更新日程时间时必须同时传 `--start` |
+| `--start <time>` | 否 | 新开始时间（ISO 8601，**必须带时区偏移**，如 `2026-03-12T14:00+08:00`；不带偏移会按进程时区解析致偏移）。更新日程时间时必须同时传 `--end` |
+| `--end <time>` | 否 | 新结束时间（ISO 8601，**必须带时区偏移**）。更新日程时间时必须同时传 `--start` |
 | `--rrule <rrule>` | 否 | 新重复规则（RFC5545）。**不要使用 COUNT；如需限制次数，推算后转为 UNTIL** |
 | `--add-attendee-ids <id_list>` | 否 | 增量添加参会人/会议室，逗号分隔。支持用户 `ou_`、群组 `oc_`、会议室 `omm_` |
 | `--remove-attendee-ids <id_list>` | 否 | 增量移除参会人/会议室，逗号分隔。支持用户 `ou_`、群组 `oc_`、会议室 `omm_` |
@@ -78,7 +78,7 @@ lark-cli calendar +update \
 
 如需更新 `location`（地理位置，不含会议室位置）、`visibility`（日程公开范围）、自定义 `reminders`（提醒设置）、自定义 `attendee_ability`（参与人权限）、自定义 `free_busy_status`（日程忙闲状态）、`color`（颜色）、附件、视频会议信息、全天日程，或在新增参会人时配置可选参加状态 等高级参数，请改用完整的 API 命令。建议先通过 `lark-cli schema calendar.events.patch`、`lark-cli schema calendar.event.attendees.create`、`lark-cli schema calendar.event.attendees.batch_delete` 查看完整参数定义。
 
-> 完整 API 命令的时间参数是 **Unix 秒字符串**（非 ISO 8601）。
+> 完整 API 命令的时间参数是 **Unix 秒字符串**（非 ISO 8601）。换算时**禁止依赖容器默认时区**（常为 UTC，会导致 8 小时偏移），必须显式指定目标时区。
 
 ## 预约/改约会议室场景
 

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

@@ -17,6 +17,9 @@
 # 创建 XML 文档（默认格式，推荐）
 lark-cli docs +create --content '<title>项目计划</title><h1>目标</h1><p>记录本周重点。</p>'
 
+# 正文中直接插入当前目录内的本地图片和附件
+lark-cli docs +create --content '<title>周报</title><img path="@images/chart.png"/><source path="@files/report.pdf"/>'
+
 # 仅当用户明确要求导入 Markdown 时才使用；文档标题用 --title，正文标题按内容自然组织
 lark-cli docs +create --doc-format markdown --title "项目计划" --content $'## 目标\n\n- 明确重点\n- 记录待办'
 ```
@@ -41,6 +44,7 @@ lark-cli docs +create --doc-format markdown --title "项目计划" --content $'#
 ```
 
 - **`document.new_blocks`**：本次操作新增的 block 列表（如画板）。`block_id` 可用于 `docs +update` 的 `--block-id` 做精确编辑；`block_token` 是资源块（如画板）的 token，可交给 `lark-whiteboard` 等 skill 继续操作
+- 正文包含 `<img path="@relative">`、`<source path="@relative">` 或 Markdown `![alt](@relative)` 时，CLI 会在创建文档后自动上传本地资源并回填 token；路径只允许位于当前工作目录内。全部成功时输出结构不变，`new_blocks[].block_token` 已替换为真实媒体 token；部分失败时返回 `ok:false` 和逐项 `summary/items`，但不会回滚正文或已成功资源。
 
 > \[!IMPORTANT]
 > 如果文档是**以应用身份（bot）创建**的，如 `lark-cli docs +create --as bot` 在文档创建成功后，CLI 会**尝试为当前 CLI 用户自动授予该文档的 `full_access`（可管理权限）**。

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

@@ -66,6 +66,19 @@ Markdown 格式支持通过 URL 插入网络图片，图片将自动从 HTTP 下
 - URL 支持 `http://` 和 `https://` 协议
 - 对应的 XML 格式为：`<img href="https://example.com/photo.png"/>`
 
+也支持直接引用当前工作目录内的本地图片：
+```markdown
+![alt text](@images/photo.png)
+![带空格的路径](<@images/product shot.png>)
+```
+- 路径必须以 `@` 开头，并且是当前工作目录内的相对路径；绝对路径、目录穿越、逃逸到目录外的符号链接、目录和空文件都会在写文档前被拒绝。
+- `![alt]` 的描述会作为图片 caption 落盘，后续导出 Markdown 时仍会恢复为图片 alt。
+- 代码围栏、行内代码、四空格/Tab 缩进代码、HTML/XML 注释和 CDATA 中的图片或附件语法不会被处理。
+- 本地图片暂不支持引用式写法（如 `![alt][ref]` + `[ref]: @image.png`）；请改用上面的行内写法。
+- 本地附件没有 Markdown 原生简写；使用 `<source path="@files/report.pdf"/>`。
+- 在 `docs +update` 中，本地图片和附件只允许配合 `append` 或 `block_insert_after`，其他写入指令会在 API 调用前被拒绝。
+- CLI 不会把本地路径发送给文档服务。写入成功后返回的 `document.new_blocks[].block_token` 是真实媒体 token；如果部分资源失败，正文和已成功资源会保留，失败占位会尽力清理并通过结构化 `summary/items` 报告。
+
 ## Markdown 不支持的 Block 类型
 
 非原生 Markdown 语法的内容（如下划线、高亮框(Callout)、勾选框、多维表格、画板、思维导图、电子表格、网格布局、引用(@文档/@人)、按钮、日期提醒、行内文件、文字颜色/背景色、同步块等）采用 XML 语法表示，详见 [`lark-doc-xml.md`](lark-doc-xml.md)。

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

@@ -56,6 +56,8 @@
 
 ### str_replace — 全文文本替换
 
+> 本地图片和附件只允许用于 `append` 或 `block_insert_after`。`str_replace` 不会创建资源 block，而 `block_replace` / `overwrite` 一旦在后续上传绑定失败会先破坏旧内容，因此 CLI 会在写文档前拒绝这些组合。
+
 > **匹配范围：**
 > - **XML 模式（默认）**：`--pattern` 只支持**行内匹配**，不能跨 block / 跨段落匹配。涉及整段或多 block 的改动，请改用 `block_replace`。
 > - **Markdown 模式**（`--doc-format markdown`）：`--pattern` 同时支持**行内和跨行匹配**，可以用多行字符串匹配并替换一整段内容。
@@ -144,6 +146,10 @@ lark-cli docs +update --doc "<doc_id>" --command overwrite \
 ```bash
 lark-cli docs +update --doc "<doc_id>" --command append \
   --content '<h2>新增章节</h2><p>追加的内容</p>'
+
+# 追加当前目录内的本地图片和附件；wiki URL 会先解析为实际 docx token
+lark-cli docs +update --doc "<doc_id或wiki_url>" --command append \
+  --content '<img path="@images/chart.png"/><source path="@files/report.pdf"/>'
 ```
 
 > 等价于 `block_insert_after --block-id -1`，无需先获取 block ID。
@@ -197,6 +203,8 @@ lark-cli docs +update --doc "<doc_id>" --command block_move_after \
 | `warnings` | 警告信息列表 |
 | `document.new_blocks` | 本次操作新增的 block 列表（如画板）。`block_id` 可用于后续精确编辑；`block_token` 是资源块 token（如画板）可交给 `lark-whiteboard` 等 skill 继续操作 |
 
+仅 `append` / `block_insert_after` 可写入本地图片或附件。CLI 会使用本次 `new_blocks` 中的占位标记严格关联 block，完成上传和 token 回填；wiki URL 会先通过 `wiki:node:retrieve` 解析为实际 docx token，再执行写入、上传和绑定。路径不会发送到服务端；全部成功时仍使用上面的既有输出结构，部分失败时增加结构化 `summary/items`，保留正文和已经成功的资源，并清理确认仍为空的失败占位。
+
 ## 典型工作流
 
 ### 精确 block 级更新
@@ -241,7 +249,7 @@ lark-cli docs +update --doc "<doc_id>" --command str_replace \
   - **XML 模式（默认）**：`--pattern` 只支持**行内**匹配，不支持跨行 / 跨 block。段落、整块或容器级（列表、表格、分栏、引用块等）改动请改用 `block_replace` 指定 block_id 重建。
   - **Markdown 模式**（`--doc-format markdown`）：`--pattern` 同时支持**行内和跨行**匹配，还支持 `前缀...后缀` 省略号语法（用 `...` 串联首尾片段匹配一大段内容），可以一次替换多行文本；但仍建议优先按最小片段匹配，跨 block 容器级重写仍优先用 `block_replace`，避免副作用。
 - **保护不可重建的内容**：图片、画板、电子表格等以 token 形式存储，替换时避开这些 block
-- **str_replace 的 replacement 支持富文本**：可以用行内标签 `<b>`、`<a>`、`<cite>`、`<latex>` 等替换普通文本为富文本
+- **str_replace 的 replacement 支持行内富文本**：可以用 `<b>`、`<a>`、`<cite>`、`<latex>` 等替换普通文本为富文本，但不支持需要新建 block 的本地图片或附件
 - **同一 block 只能被 replace 一次**：多次修改同一 block 请合并为一次 block_replace
 - **block_delete 支持批量**：用逗号分隔多个 block_id 一次删除
 - **复杂结构重组**：将多个段落转换为 grid / table 等复杂布局时，分步操作比 overwrite 更安全：

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

@@ -26,8 +26,8 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 | `<cite type="user">` | @人 | XML 导入时必须显式传入 `user-id`：`<cite type="user" user-id="userID"></cite>` |
 | `<cite type="doc">` | @文档 | `<cite type="doc" doc-id="docx_token"></cite>` |
 | `<latex>` | 行内公式 | `<latex>E = mc^2</latex>` |
-| `<img>` | 图片（可独立成块或内联） | `<img width="800" height="600" caption="说明" name="图.png" href="http 或 https"/>` |
-| `<source>` | 文件附件（可独立成块或内联） | `<source name="报告.pdf"/>` |
+| `<img>` | 图片（可独立成块或内联） | 网络图片：`<img href="https://..."/>`；当前目录内本地图片：`<img path="@images/a.png"/>` |
+| `<source>` | 文件附件（可独立成块或内联） | 当前目录内本地文件：`<source path="@files/report.pdf" name="报告.pdf"/>` |
 | `<a type="url-preview">` | 预览卡片 | `<a type="url-preview" href="...">标题</a>` |
 | `<button>` | 操作按钮 | `background-color`、`src`，必须包含 `action=OpenLink\|DuplicatePage\|FollowPage` |
 | `<time>` | 提醒 | 必包含 `expire-time`、`notify-time`（毫秒时间戳）、`should-notify=true\|false` |
@@ -41,6 +41,9 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 文档中可嵌入外部资源块（属于容器标签的特殊形式），需要额外语法创建：
 
 - `<img>` — `<img href="https://..."/>` 上传网络图片
+- `<img path="@relative/path.png" caption="说明"/>` — 在 `docs +create`，或 `docs +update --command append/block_insert_after` 中直接插入本地图片；`path` 必须是当前工作目录内的相对路径，不能与 `src` / `href` / `token` / `img_key` 同时使用。CLI 会先创建占位 block，再上传并回填真实 token；同一文件出现多次会分别上传、分别挂载。兼容旧写法 `alt="说明"`：未显式提供 `caption` 时 CLI 会将 `alt` 映射为 caption。
+- `<source path="@relative/report.pdf" name="自定义文件名.pdf"/>` — 直接插入本地附件；路径与来源互斥规则同本地图片。`name` 可选，提供时会作为上传后的附件名；附件没有额外的 Markdown 简写，应在 XML 或 Markdown 正文中使用这个原始 XML 标签。
+- XML/HTML 注释与 CDATA 中的 `<img path>` / `<source path>` 仅作为字面内容，不会触发本地文件读取或上传。
 - `<whiteboard>` — 简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整自包含 SVG</whiteboard>`；也可用本地文件简写 `<whiteboard type="svg" path="@diagram.svg"></whiteboard>`、`<whiteboard type="mermaid" path="@flow.mmd"></whiteboard>`、`<whiteboard type="plantuml" path="@sequence.puml"></whiteboard>`，CLI 会写入前展开为内联内容；复杂图使用 `<whiteboard type="blank"></whiteboard>` 先创建空白画板，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 调用 `lark-whiteboard` 写入；
 - `<sheet>` — `<sheet type="blank"></sheet>` 空白；`<sheet sheet-id="SID" token="TOKEN"></sheet>` 复制已有
 - `<task>` — `<task task-id="GUID"></task>`，必传 task-id（任务 guid）
@@ -167,8 +170,10 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 <hr/>
 
 <source name="文件名.pdf"/>
+<source path="@files/报告.pdf" name="报告.pdf"/>
 <img src="IMG_TOKEN" width="800" height="400" caption="说明" name="图.png"/>
 <img href="https://example.com/photo.png"/>
+<img path="@images/photo.png" width="800" align="center" caption="说明"/>
 
 <button action="OpenLink" src="https://example.com">按钮文字</button>
 

tests/cli_e2e/base/base_form_questions_dryrun_test.go

@@ -0,0 +1,69 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestBaseFormQuestionsCreateVisibleRuleDryRun(t *testing.T) {
+	setBaseDryRunConfigEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"base", "+form-questions-create",
+			"--base-token", "bascnXXXX",
+			"--table-id", "tblXXXX",
+			"--form-id", "vewXXXX",
+			"--questions", `[{"type":"text","title":"发票抬头","visible_rule":{"logic":"and","conditions":[["是否需要发票","==","是"]]}}]`,
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	output := strings.TrimSpace(result.Stdout)
+	assert.Contains(t, output, "/open-apis/base/v3/bases/bascnXXXX/tables/tblXXXX/forms/vewXXXX/questions")
+	assert.Contains(t, output, `"method": "POST"`)
+	// visible_rule must be transcribed verbatim into the request body.
+	assert.Contains(t, output, "visible_rule")
+	assert.Contains(t, output, "是否需要发票")
+}
+
+func TestBaseFormQuestionsUpdateVisibleRuleDryRun(t *testing.T) {
+	setBaseDryRunConfigEnv(t)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"base", "+form-questions-update",
+			"--base-token", "bascnXXXX",
+			"--table-id", "tblXXXX",
+			"--form-id", "vewXXXX",
+			"--questions", `[{"id":"q_002","visible_rule":{"logic":"and","conditions":[["q_001","==","是"]]}}]`,
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	output := strings.TrimSpace(result.Stdout)
+	assert.Contains(t, output, "/open-apis/base/v3/bases/bascnXXXX/tables/tblXXXX/forms/vewXXXX/questions")
+	assert.Contains(t, output, `"method": "PATCH"`)
+	assert.Contains(t, output, "visible_rule")
+}

tests/cli_e2e/base/coverage.md

@@ -12,6 +12,7 @@
 - TestBaseRecordBatchUpdatePerRecordDryRun: proves `+record-batch-update` preserves the per-record `update_records` request shape.
 - TestBaseRecordBatchUpdatePerRecordWorkflow: creates two records, updates different field types in one request, asserts the minimal response contract, reads both records back, verifies a missing record ID is not prevalidated, and cleans up the temporary Base.
 - TestBase_RoleWorkflow: proves `+advperm-enable`, `+role-create`, `+role-list`, `+role-get`, and `+role-update`; key `t.Run(...)` proof points are `list as bot`, `get as bot`, and `update as bot`.
+- TestBaseFormQuestionsCreateVisibleRuleDryRun / TestBaseFormQuestionsUpdateVisibleRuleDryRun: prove `+form-questions-create` / `+form-questions-update` dry-run request shape and that the optional `visible_rule` display condition is transcribed verbatim into the request body.
 - Cleanup note: `+table-delete` and `+role-delete` only run in cleanup and are intentionally left uncovered.
 - Blocked area: dashboard, field, most record operations, form, view, and workflow operations still lack deterministic create/read/update workflows in this suite.
 
@@ -51,10 +52,10 @@
 | ✕ | base +form-delete | shortcut |  | none | form workflows not covered |
 | ✕ | base +form-get | shortcut |  | none | form workflows not covered |
 | ✕ | base +form-list | shortcut |  | none | form workflows not covered |
-| ✕ | base +form-questions-create | shortcut |  | none | form workflows not covered |
+| ✓ | base +form-questions-create | shortcut | TestBaseFormQuestionsCreateVisibleRuleDryRun | questions[].visible_rule | dry-run: request shape + visible_rule body passthrough |
 | ✕ | base +form-questions-delete | shortcut |  | none | form workflows not covered |
 | ✕ | base +form-questions-list | shortcut |  | none | form workflows not covered |
-| ✕ | base +form-questions-update | shortcut |  | none | form workflows not covered |
+| ✓ | base +form-questions-update | shortcut | TestBaseFormQuestionsUpdateVisibleRuleDryRun | questions[].visible_rule | dry-run: request shape + visible_rule body passthrough |
 | ✕ | base +form-update | shortcut |  | none | form workflows not covered |
 | ✓ | base +record-batch-create | shortcut | base_record_batch_update_workflow_test.go::TestBaseRecordBatchUpdatePerRecordWorkflow | `--base-token`; `--table-id`; `--json.create_records` | seeds heterogeneous live workflow records |
 | ✓ | base +record-batch-update | shortcut | base_record_batch_update_dryrun_test.go::TestBaseRecordBatchUpdatePerRecordDryRun; base_record_batch_update_workflow_test.go::TestBaseRecordBatchUpdatePerRecordWorkflow | `--base-token`; `--table-id`; `--json.update_records`; dry-run + live | heterogeneous select/number update with write-back verification |

tests/cli_e2e/docs/coverage.md

@@ -9,19 +9,21 @@
 - TestDocs_CreateAndFetchWorkflow: proves `docs +create` and `docs +fetch`; key `t.Run(...)` proof points are `create as bot` and `fetch as bot`.
 - TestDocs_CreateAndFetchWorkflowAsUser: proves the same shortcut pair with UAT injection via `create as user` and `fetch as user`; creates its own Drive folder fixture first, then reads back the created doc by token.
 - TestDocs_UpdateWorkflow: proves `docs +update` via `update-title-and-content as bot`, then re-fetches the same doc in `verify as bot` to assert persisted title/content changes.
+- TestDocs_LocalResourcesWorkflowAsBot / AsUser: prove the full local image + file lifecycle for `docs +create` and `docs +update --command append`: placeholder correlation, distinct media block IDs, local image intrinsic-dimension detection, model display-size conversion to persisted `scale`, invalid `width`/`height`/`size` normalization, media upload, token binding, response scrubbing, XML/Markdown fetch verification, exported-Markdown replay with image caption restoration, and cleanup.
+- TestDocs_LocalResourcesDryRun: proves both `docs +create` and `docs +update --command append` expose the complete no-network request plan for local images and files: placeholder content with intrinsic dimensions, media uploads, image binding with intrinsic `width`/`height` plus converted `scale`, file binding, conditional verification, and failure cleanup.
 - TestDocs_DryRunDefaultsToV2OpenAPI: proves `docs +create`, `docs +fetch`, and `docs +update` dry-run all emit `/open-apis/docs_ai/v1/...` requests without MCP or `--api-version` guidance; its fetch case asserts fetch sends the default `extra_param`, and its update case asserts `--reference-map` is sent as request body `reference_map`.
 - TestDocs_CreateTitleDryRunPrependsContent: proves `docs +create --title` dry-run prepends an escaped `<title>...</title>` tag to request body `content`.
 - TestDocs_DryRunDefaultsToV2OpenAPI also proves `docs +history-list`, `docs +history-revert`, and `docs +history-revert-status` dry-run endpoint and query/body shapes.
 - TestDocs_HistoryWorkflow proves the guarded live history flow (`LARK_DOC_HISTORY_E2E=1`): create, update, list prior revisions, revert, poll status when needed, and fetch to verify reverted content.
 - Setup note: docs workflows create a Drive folder through `drive files create_folder` in `helpers_test.go`; that helper is external to the docs domain and is not counted here.
-- Blocked area: media and search shortcuts still need deterministic fixtures and local file orchestration.
+- Blocked area: standalone media and search shortcuts still need dedicated deterministic workflows; local resource authoring through create/update is covered.
 
 ## Command Table
 
 | Status | Cmd | Type | Testcase | Key parameter shapes | Notes / uncovered reason |
 | --- | --- | --- | --- | --- | --- |
-| ✓ | docs +create | shortcut | docs/helpers_test.go::createDocWithRetry; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/create as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/create; docs_update_dryrun_test.go::TestDocs_CreateTitleDryRunPrependsContent | `--parent-token`; `--doc-format markdown`; `--content`; `--title` | helper asserts returned doc id from `data.document.document_id`; dry-run asserts title is prepended into request body content |
-| ✓ | docs +fetch | shortcut | docs_fetch_dryrun_test.go::TestDocsFetchDryRunIgnoresAPIVersionCompatFlag; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflow/fetch as bot; docs_update_test.go::TestDocs_UpdateWorkflow/verify as bot; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/fetch as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/fetch | `--doc <docToken>`; `--doc-format markdown`; default `extra_param.enable_user_cite_reference_map=true`; `--api-version v1` compatibility flag still dry-runs the v2 fetch endpoint | |
+| ✓ | docs +create | shortcut | docs/helpers_test.go::createDocWithRetry; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/create as user; docs_local_resources_workflow_test.go::TestDocs_LocalResourcesWorkflowAsBot/create image and source; docs_local_resources_workflow_test.go::TestDocs_LocalResourcesWorkflowAsUser/create image and source; docs_local_resources_dryrun_test.go::TestDocs_LocalResourcesDryRun/create; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/create; docs_update_dryrun_test.go::TestDocs_CreateTitleDryRunPrependsContent | `--parent-token`; `--doc-format markdown`; `--content`; `--title`; XML `<img path="@relative" width="display-px">` + `<source path="@relative">` | local-resource workflows assert returned image/file block IDs and bound tokens; image binding preserves intrinsic dimensions and converts display size to `scale` |
+| ✓ | docs +fetch | shortcut | docs_fetch_dryrun_test.go::TestDocsFetchDryRunIgnoresAPIVersionCompatFlag; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflow/fetch as bot; docs_update_test.go::TestDocs_UpdateWorkflow/verify as bot; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/fetch as user; docs_local_resources_workflow_test.go::testDocsLocalResourcesWorkflow/fetch verifies persisted resources; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/fetch | `--doc <docToken>`; `--doc-format markdown|xml`; `--detail full`; default `extra_param.enable_user_cite_reference_map=true`; `--api-version v1` compatibility flag still dry-runs the v2 fetch endpoint | local-resource fetch asserts captions/file names persist and internal markers/paths do not leak |
 | ✓ | docs +history-list | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history list; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--page-size`; `--page-token` | live workflow gated by `LARK_DOC_HISTORY_E2E=1` |
 | ✓ | docs +history-revert | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history revert; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--history-version-id`; `--wait-timeout-ms` | live workflow gated by `LARK_DOC_HISTORY_E2E=1` |
 | ✓ | docs +history-revert-status | shortcut | docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/history revert status; docs_history_workflow_test.go::TestDocs_HistoryWorkflow | `--doc`; `--task-id` | live workflow polls only when revert returns `running` |
@@ -29,5 +31,5 @@
 | ✕ | docs +media-insert | shortcut |  | none | requires deterministic upload fixture and rollback assertions |
 | ✕ | docs +media-preview | shortcut |  | none | requires deterministic media fixture |
 | ✕ | docs +search | shortcut |  | none | search results are ambient and not yet stabilized for E2E |
-| ✓ | docs +update | shortcut | docs_update_test.go::TestDocs_UpdateWorkflow/update-title-and-content as bot; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/update | `--doc`; `--command overwrite`; `--doc-format markdown`; `--content`; optional `--reference-map` -> body `reference_map` | |
+| ✓ | docs +update | shortcut | docs_update_test.go::TestDocs_UpdateWorkflow/update-title-and-content as bot; docs_local_resources_workflow_test.go::testDocsLocalResourcesWorkflow/append image and source; docs_local_resources_dryrun_test.go::TestDocs_LocalResourcesDryRun/update append; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/update | `--doc`; `--command overwrite|append`; `--doc-format markdown|xml`; `--content`; local `<img path>` / `<source path>`; optional `--reference-map` -> body `reference_map` | local resources are covered under both bot and user identities |
 | ✕ | docs +whiteboard-update | shortcut |  | none | requires whiteboard fixture and DSL-specific assertions |

tests/cli_e2e/docs/docs_local_resources_dryrun_test.go

@@ -0,0 +1,100 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package docs
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/require"
+)
+
+func TestDocs_LocalResourcesDryRun(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
+	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
+	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	workDir := t.TempDir()
+	writeLocalResourceFixture(t, workDir, "dry-run.png", hundredByEightyPNG)
+	writeLocalResourceFixture(t, workDir, "dry-run.txt", []byte("dry-run source fixture\n"))
+	content := `<p>dry-run resources</p><img path="@dry-run.png" caption="dry-run image" width="50"/><source path="@dry-run.txt" name="dry-run-report.txt"/>`
+
+	tests := []struct {
+		name            string
+		args            []string
+		wantDocumentURL string
+	}{
+		{
+			name: "create",
+			args: []string{
+				"docs", "+create",
+				"--title", "Local resources dry-run",
+				"--content", content,
+				"--dry-run",
+			},
+			wantDocumentURL: "/open-apis/docs_ai/v1/documents",
+		},
+		{
+			name: "update append",
+			args: []string{
+				"docs", "+update",
+				"--doc", "doxcnLocalResourcesDryRun",
+				"--command", "append",
+				"--content", content,
+				"--dry-run",
+			},
+			wantDocumentURL: "/open-apis/docs_ai/v1/documents/doxcnLocalResourcesDryRun",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result, err := clie2e.RunCmd(ctx, clie2e.Request{
+				Args:      tt.args,
+				DefaultAs: "bot",
+				WorkDir:   workDir,
+			})
+			require.NoError(t, err)
+			result.AssertExitCode(t, 0)
+
+			apis := clie2e.DryRunGet(result.Stdout, "api").Array()
+			require.Len(t, apis, 6, "stdout:\n%s", result.Stdout)
+			require.Equal(t, tt.wantDocumentURL, apis[0].Get("url").String(), "stdout:\n%s", result.Stdout)
+
+			preparedContent := apis[0].Get("body.content").String()
+			require.Contains(t, preparedContent, "dry-run image")
+			require.Contains(t, preparedContent, "dry-run-report.txt")
+			require.NotContains(t, preparedContent, "@dry-run.png")
+			require.NotContains(t, preparedContent, "@dry-run.txt")
+			require.Equal(t, 2, strings.Count(preparedContent, "@lcli_"), "prepared content:\n%s", preparedContent)
+
+			require.Equal(t, "/open-apis/drive/v1/medias/upload_all", apis[1].Get("url").String())
+			require.Equal(t, "docx_image", apis[1].Get("body.parent_type").String())
+			require.Equal(t, "<local_image_1_block_id>", apis[1].Get("body.parent_node").String())
+			require.Equal(t, "/open-apis/drive/v1/medias/upload_all", apis[2].Get("url").String())
+			require.Equal(t, "docx_file", apis[2].Get("body.parent_type").String())
+			require.Equal(t, "<local_file_2_block_id>", apis[2].Get("body.parent_node").String())
+
+			require.Contains(t, apis[3].Get("url").String(), "/open-apis/docx/v1/documents/")
+			require.Contains(t, apis[3].Get("url").String(), "/blocks/batch_update")
+			require.NotEmpty(t, apis[3].Get("params.client_token").String())
+			require.Equal(t, "<uploaded_file_token_1>", apis[3].Get("body.requests.0.replace_image.token").String())
+			require.Equal(t, int64(100), apis[3].Get("body.requests.0.replace_image.width").Int())
+			require.Equal(t, int64(80), apis[3].Get("body.requests.0.replace_image.height").Int())
+			require.InDelta(t, 0.5, apis[3].Get("body.requests.0.replace_image.scale").Float(), 0.000001)
+			require.Equal(t, "<uploaded_file_token_2>", apis[3].Get("body.requests.1.replace_file.token").String())
+
+			require.Equal(t, "GET", apis[4].Get("method").String())
+			require.Equal(t, "PUT", apis[5].Get("method").String())
+			require.Contains(t, apis[5].Get("url").String(), "/open-apis/docs_ai/v1/documents/")
+			require.Equal(t, "block_delete", apis[5].Get("body.command").String())
+		})
+	}
+}

tests/cli_e2e/docs/docs_local_resources_workflow_test.go

@@ -0,0 +1,309 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package docs
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"image"
+	"image/png"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/larksuite/cli/tests/cli_e2e/drive"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+func TestDocs_LocalResourcesWorkflowAsBot(t *testing.T) {
+	testDocsLocalResourcesWorkflow(t, "bot")
+}
+
+func TestDocs_LocalResourcesWorkflowAsUser(t *testing.T) {
+	clie2e.SkipWithoutUserToken(t)
+	testDocsLocalResourcesWorkflow(t, "user")
+}
+
+func testDocsLocalResourcesWorkflow(t *testing.T, defaultAs string) {
+	t.Helper()
+	if os.Getenv("LARK_DOC_LOCAL_RESOURCES_E2E") != "1" {
+		t.Skip("set LARK_DOC_LOCAL_RESOURCES_E2E=1 and use a server lane with local-resource placeholder support")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 4*time.Minute)
+	t.Cleanup(cancel)
+
+	workDir := t.TempDir()
+	createdSource := []byte("created source fixture\n")
+	appendedNegativeSource := []byte("appended negative source fixture\n")
+	appendedNonNumericSource := []byte("appended nonnumeric source fixture\n")
+	writeLocalResourceFixture(t, workDir, "created.png", hundredByEightyPNG)
+	writeLocalResourceFixture(t, workDir, "created.txt", createdSource)
+	writeLocalResourceFixture(t, workDir, "appended.png", onePixelPNG)
+	writeLocalResourceFixture(t, workDir, "appended-negative.txt", appendedNegativeSource)
+	writeLocalResourceFixture(t, workDir, "appended-nonnumeric.txt", appendedNonNumericSource)
+
+	suffix := clie2e.GenerateSuffix()
+	parentT := t
+	folderToken := ""
+	cleanupAs := defaultAs
+	if defaultAs == "bot" {
+		// Bot-created documents grant the current CLI user full access, while
+		// the shared PPE bot intentionally lacks Drive delete scopes.
+		cleanupAs = "user"
+	} else {
+		folderToken = drive.CreateDriveFolder(t, parentT, ctx, "lark-cli-e2e-local-resources-"+suffix, defaultAs, "")
+	}
+	var docToken string
+	var roundTripDocToken string
+	var roundTripContent string
+
+	t.Run("create image and source", func(t *testing.T) {
+		args := []string{
+			"docs", "+create",
+			"--title", "lark-cli local resources " + suffix,
+			"--content", `<p>created resources</p><img path="@created.png" caption="created image" width="50"/><source path="@created.txt" name="created-report.txt" size="0"/>`,
+		}
+		if folderToken != "" {
+			args = append(args, "--parent-token", folderToken)
+		}
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args:      args,
+			DefaultAs: defaultAs,
+			WorkDir:   workDir,
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		result.AssertStdoutStatus(t, true)
+		assertBoundLocalResourceBlocks(t, result.Stdout, 1, 1)
+
+		docToken = gjson.Get(result.Stdout, "data.document.document_id").String()
+		require.NotEmpty(t, docToken, "stdout:\n%s", result.Stdout)
+		parentT.Cleanup(func() {
+			cleanupCtx, cleanupCancel := clie2e.CleanupContext()
+			defer cleanupCancel()
+			deleteResult, deleteErr := drive.DeleteDriveResourceAndVerify(cleanupCtx, docToken, "docx", cleanupAs)
+			clie2e.ReportCleanupFailure(parentT, "delete doc "+docToken, deleteResult, deleteErr)
+		})
+	})
+
+	t.Run("append image and source", func(t *testing.T) {
+		require.NotEmpty(t, docToken, "document token should be created before update")
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"docs", "+update",
+				"--doc", docToken,
+				"--command", "append",
+				"--content", `<p>appended resources</p><img path="@appended.png" caption="appended image" width="invalid" height="0"/><source path="@appended-negative.txt" name="appended-negative-report.txt" size="-2"/><source path="@appended-nonnumeric.txt" name="appended-nonnumeric-report.txt" size="invalid"/>`,
+			},
+			DefaultAs: defaultAs,
+			WorkDir:   workDir,
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		result.AssertStdoutStatus(t, true)
+		assertBoundLocalResourceBlocks(t, result.Stdout, 1, 2)
+	})
+
+	t.Run("fetch verifies persisted resources", func(t *testing.T) {
+		require.NotEmpty(t, docToken, "document token should be created before fetch")
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"docs", "+fetch",
+				"--doc", docToken,
+				"--doc-format", "xml",
+				"--detail", "full",
+			},
+			DefaultAs: defaultAs,
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		result.AssertStdoutStatus(t, true)
+
+		content := gjson.Get(result.Stdout, "data.document.content").String()
+		for _, want := range []string{
+			"created image",
+			"appended image",
+			"created-report.txt",
+			"appended-negative-report.txt",
+			"appended-nonnumeric-report.txt",
+		} {
+			require.Contains(t, content, want, "fetched XML:\n%s", content)
+		}
+		require.NotContains(t, content, "@lcli_", "fetched XML leaked internal correlation marker")
+		require.NotContains(t, content, "@created.", "fetched XML leaked create fixture path")
+		require.NotContains(t, content, "@appended.", "fetched XML leaked append fixture path")
+		assertFetchedImagePresentation(t, content, "created image", 100, 80, 0.5)
+	})
+
+	t.Run("fetch markdown preserves resource metadata", func(t *testing.T) {
+		require.NotEmpty(t, docToken, "document token should be created before fetch")
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"docs", "+fetch",
+				"--doc", docToken,
+				"--doc-format", "markdown",
+				"--detail", "full",
+			},
+			DefaultAs: defaultAs,
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		result.AssertStdoutStatus(t, true)
+
+		content := gjson.Get(result.Stdout, "data.document.content").String()
+		for _, want := range []string{"![created image](", "![appended image]("} {
+			require.Contains(t, content, want, "fetched Markdown:\n%s", content)
+		}
+		assertMarkdownSourceMetadata(t, content, "created-report.txt", len(createdSource))
+		assertMarkdownSourceMetadata(t, content, "appended-negative-report.txt", len(appendedNegativeSource))
+		assertMarkdownSourceMetadata(t, content, "appended-nonnumeric-report.txt", len(appendedNonNumericSource))
+		require.NotContains(t, content, "@lcli_", "fetched Markdown leaked internal correlation marker")
+		require.NotContains(t, content, "@created.", "fetched Markdown leaked create fixture path")
+		require.NotContains(t, content, "@appended.", "fetched Markdown leaked append fixture path")
+
+		roundTripContent = content
+	})
+
+	t.Run("create from exported markdown restores image captions", func(t *testing.T) {
+		require.NotEmpty(t, roundTripContent, "Markdown content should be fetched before replay")
+		args := []string{
+			"docs", "+create",
+			"--title", "lark-cli markdown replay " + suffix,
+			"--doc-format", "markdown",
+			"--content", "-",
+		}
+		if folderToken != "" {
+			args = append(args, "--parent-token", folderToken)
+		}
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args:      args,
+			DefaultAs: defaultAs,
+			Stdin:     []byte(roundTripContent),
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		result.AssertStdoutStatus(t, true)
+
+		roundTripDocToken = gjson.Get(result.Stdout, "data.document.document_id").String()
+		require.NotEmpty(t, roundTripDocToken, "stdout:\n%s", result.Stdout)
+		parentT.Cleanup(func() {
+			cleanupCtx, cleanupCancel := clie2e.CleanupContext()
+			defer cleanupCancel()
+			deleteResult, deleteErr := drive.DeleteDriveResourceAndVerify(cleanupCtx, roundTripDocToken, "docx", cleanupAs)
+			clie2e.ReportCleanupFailure(parentT, "delete markdown replay doc "+roundTripDocToken, deleteResult, deleteErr)
+		})
+	})
+
+	t.Run("fetch markdown replay verifies captions and source metadata", func(t *testing.T) {
+		require.NotEmpty(t, roundTripDocToken, "Markdown replay document should be created before fetch")
+		result, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"docs", "+fetch",
+				"--doc", roundTripDocToken,
+				"--doc-format", "xml",
+				"--detail", "full",
+			},
+			DefaultAs: defaultAs,
+		})
+		require.NoError(t, err)
+		result.AssertExitCode(t, 0)
+		result.AssertStdoutStatus(t, true)
+
+		content := gjson.Get(result.Stdout, "data.document.content").String()
+		for _, want := range []string{
+			`caption="created image`,
+			`caption="appended image`,
+		} {
+			require.Contains(t, content, want, "replayed XML:\n%s", content)
+		}
+		for _, want := range []string{
+			"created-report.txt",
+			"appended-negative-report.txt",
+			"appended-nonnumeric-report.txt",
+		} {
+			require.Contains(t, content, want, "replayed XML:\n%s", content)
+		}
+	})
+}
+
+var markdownSourceTagPattern = regexp.MustCompile(`(?s)<source\b[^>]*>`)
+
+func assertMarkdownSourceMetadata(t *testing.T, content, wantName string, wantSize int) {
+	t.Helper()
+	wantNameAttr := fmt.Sprintf(`name="%s"`, wantName)
+	for _, tag := range markdownSourceTagPattern.FindAllString(content, -1) {
+		if !strings.Contains(tag, wantNameAttr) {
+			continue
+		}
+		require.Contains(t, tag, fmt.Sprintf(`size="%d"`, wantSize), "source tag in fetched Markdown:\n%s", tag)
+		return
+	}
+	require.Failf(t, "source metadata not found", "fetched Markdown has no source tag with %s:\n%s", wantNameAttr, content)
+}
+
+func assertBoundLocalResourceBlocks(t *testing.T, stdout string, wantImages, wantFiles int) {
+	t.Helper()
+	counts := map[string]int{"image": 0, "file": 0}
+	blockIDs := make(map[string]struct{}, wantImages+wantFiles)
+	for _, block := range gjson.Get(stdout, "data.document.new_blocks").Array() {
+		blockType := block.Get("block_type").String()
+		if _, tracked := counts[blockType]; !tracked {
+			continue
+		}
+		counts[blockType]++
+		blockID := block.Get("block_id").String()
+		require.NotEmpty(t, blockID, "%s block has no block_id: %s", blockType, block.Raw)
+		require.NotContains(t, blockIDs, blockID, "multiple local resources reused block_id %s: %s", blockID, stdout)
+		blockIDs[blockID] = struct{}{}
+		token := block.Get("block_token").String()
+		require.NotEmpty(t, token, "%s block has no bound token: %s", blockType, block.Raw)
+		require.False(t, strings.HasPrefix(token, "@lcli_"), "%s block leaked marker: %s", blockType, block.Raw)
+	}
+	require.Equal(t, wantImages, counts["image"], "image blocks in stdout:\n%s", stdout)
+	require.Equal(t, wantFiles, counts["file"], "file blocks in stdout:\n%s", stdout)
+}
+
+func writeLocalResourceFixture(t *testing.T, dir, name string, data []byte) {
+	t.Helper()
+	path := filepath.Join(dir, name)
+	require.NoError(t, os.WriteFile(path, data, 0o600))
+}
+
+func assertFetchedImagePresentation(t *testing.T, content, caption string, width, height int, scale float64) {
+	t.Helper()
+	for _, tag := range regexp.MustCompile(`(?s)<img\b[^>]*>`).FindAllString(content, -1) {
+		if !strings.Contains(tag, fmt.Sprintf(`caption="%s"`, caption)) {
+			continue
+		}
+		require.Contains(t, tag, fmt.Sprintf(`width="%d"`, width), "image tag in fetched XML:\n%s", tag)
+		require.Contains(t, tag, fmt.Sprintf(`height="%d"`, height), "image tag in fetched XML:\n%s", tag)
+		scaleMatch := regexp.MustCompile(`\bscale="([^"]+)"`).FindStringSubmatch(tag)
+		require.Len(t, scaleMatch, 2, "image tag has no scale: %s", tag)
+		var gotScale float64
+		_, err := fmt.Sscanf(scaleMatch[1], "%f", &gotScale)
+		require.NoError(t, err, "parse image scale from %s", tag)
+		require.InDelta(t, scale, gotScale, 0.000001, "image tag in fetched XML:\n%s", tag)
+		return
+	}
+	require.Failf(t, "image presentation not found", "fetched XML has no image with caption %q:\n%s", caption, content)
+}
+
+func encodePNGFixture(width, height int) []byte {
+	var buf bytes.Buffer
+	if err := png.Encode(&buf, image.NewRGBA(image.Rect(0, 0, width, height))); err != nil {
+		panic(fmt.Sprintf("encode embedded %dx%d PNG fixture: %v", width, height, err))
+	}
+	return buf.Bytes()
+}
+
+var (
+	onePixelPNG        = encodePNGFixture(1, 1)
+	hundredByEightyPNG = encodePNGFixture(100, 80)
+)