chore(release): v1.0.32 (#918)

Change-Id: I3d1a8ec4faf1ce585fb9eae45287bf02586e3e90

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.32] - 2026-05-15
+
+### Features
+
+- **doc**: Add `--width`/`--height` flags to `docs +media-insert` (#832)
+- **wiki**: Add `+space-list` / `+node-list` / `+node-copy` shortcuts (#392)
+
+### Bug Fixes
+
+- **drive**: Preserve parent token on nested overwrite (#908)
+- **selfupdate**: Use `LookPath` instead of `Executable` for binary verification (#886)
+- **registry**: Wait for background meta refresh before test reset (#894)
+
+### Documentation
+
+- **doc**: Add SVG whiteboard support to `lark-doc` v2 skill (#901)
+- **drive**: Add permission public patch error guidance (#863)
+
 ## [v1.0.31] - 2026-05-14
 
 ### Features
@@ -703,6 +721,7 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.32]: https://github.com/larksuite/cli/releases/tag/v1.0.32
 [v1.0.31]: https://github.com/larksuite/cli/releases/tag/v1.0.31
 [v1.0.30]: https://github.com/larksuite/cli/releases/tag/v1.0.30
 [v1.0.29]: https://github.com/larksuite/cli/releases/tag/v1.0.29

cmd/config/bind_test.go

@@ -408,6 +408,26 @@ func TestConfigBindRun_LarkChannel_Success(t *testing.T) {
 	}
 }
 
+// Env template form: secret = "${VAR}" should resolve via the SecretInput
+// pipeline (same path openclaw uses), so the keychain receives the env value
+// not the literal template string.
+func TestConfigBindRun_LarkChannel_EnvTemplate(t *testing.T) {
+	saveWorkspace(t)
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	clearAgentEnv(t)
+
+	fakeHome := t.TempDir()
+	t.Setenv("HOME", fakeHome)
+	t.Setenv("LARK_APP_SECRET", "resolved_via_env")
+	writeLarkChannelFixture(t, fakeHome,
+		`{"accounts":{"app":{"id":"cli_lc_env","secret":"${LARK_APP_SECRET}","tenant":"feishu"}}}`)
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	if err := configBindRun(&BindOptions{Factory: f, Source: "lark-channel"}); err != nil {
+		t.Fatalf("expected success, got error: %v", err)
+	}
+}
+
 // tenant: "lark" should land as Brand("lark"), not normalized to "feishu".
 func TestConfigBindRun_LarkChannel_LarkTenant(t *testing.T) {
 	saveWorkspace(t)

cmd/config/binder.go

@@ -312,13 +312,22 @@ func (b *larkChannelBinder) Build(appID string) (*core.AppConfig, error) {
 		return nil, output.Errorf(output.ExitInternal, "lark-channel",
 			"internal: appID %q does not match config", appID)
 	}
-	if b.cfg.Accounts.App.Secret == "" {
+	if b.cfg.Accounts.App.Secret.IsZero() {
 		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
 			fmt.Sprintf("accounts.app.secret is empty in %s", b.path),
 			"run lark-channel-bridge's setup to populate the app credential")
 	}
 
-	stored, err := core.ForStorage(appID, core.PlainSecret(b.cfg.Accounts.App.Secret), b.opts.Factory.Keychain)
+	// Resolve through the same SecretInput pipeline openclaw uses, so
+	// bridge configs can use ${VAR} / env / file / exec just like openclaw.
+	secret, err := binding.ResolveSecretInput(b.cfg.Accounts.App.Secret, b.cfg.Secrets, os.Getenv)
+	if err != nil {
+		return nil, output.ErrWithHint(output.ExitValidation, "lark-channel",
+			fmt.Sprintf("failed to resolve appSecret for %s: %v", appID, err),
+			fmt.Sprintf("check appSecret configuration in %s", b.path))
+	}
+
+	stored, err := core.ForStorage(appID, core.PlainSecret(secret), b.opts.Factory.Keychain)
 	if err != nil {
 		return nil, output.Errorf(output.ExitInternal, "lark-channel",
 			"keychain unavailable: %v", err)

internal/binding/lark_channel.go

@@ -15,6 +15,11 @@ import (
 // Unknown fields are ignored — forward-compatible with future bridge versions.
 type LarkChannelRoot struct {
 	Accounts LarkChannelAccounts `json:"accounts"`
+	// Secrets is an optional registry of secret providers — same shape as
+	// openclaw's `secrets` block. Lets bridge declare `exec` provider scripts
+	// (for AES-encrypted secret backends), `env` allowlists, or `file`
+	// indirection rules. Resolved by binding.ResolveSecretInput.
+	Secrets *SecretsConfig `json:"secrets,omitempty"`
 }
 
 // LarkChannelAccounts is the namespace for credential entries.
@@ -26,13 +31,17 @@ type LarkChannelAccounts struct {
 }
 
 // LarkChannelApp is the bot app credential entry.
-// Bridge stores the secret as plain text — secret-resolve indirection
-// (${VAR} / file: / exec:) is intentionally not supported here, matching
-// the bridge's on-disk format.
+//
+// `Secret` accepts the full SecretInput protocol (string / "${VAR}" template /
+// SecretRef object with source env|file|exec) so users can keep secrets out
+// of config.json — either by referencing an env var the bridge inherits, a
+// chmod-0400 file outside the bridge dir, or an exec script that decrypts a
+// local AES-encrypted secret store. Aligns lark-channel with the same secret
+// protocol openclaw already uses.
 type LarkChannelApp struct {
-	ID     string `json:"id"`
-	Secret string `json:"secret"`
-	Tenant string `json:"tenant"` // "feishu" | "lark"
+	ID     string      `json:"id"`
+	Secret SecretInput `json:"secret"`
+	Tenant string      `json:"tenant"` // "feishu" | "lark"
 }
 
 // ReadLarkChannelConfig reads and parses ~/.lark-channel/config.json.

internal/binding/lark_channel_test.go

@@ -24,8 +24,11 @@ func TestReadLarkChannelConfig_Valid(t *testing.T) {
 	if got := root.Accounts.App.ID; got != "cli_abc123" {
 		t.Errorf("ID = %q, want %q", got, "cli_abc123")
 	}
-	if got := root.Accounts.App.Secret; got != "plain_secret" {
-		t.Errorf("Secret = %q, want %q", got, "plain_secret")
+	if got := root.Accounts.App.Secret.Plain; got != "plain_secret" {
+		t.Errorf("Secret.Plain = %q, want %q", got, "plain_secret")
+	}
+	if root.Accounts.App.Secret.Ref != nil {
+		t.Errorf("expected Plain form, got SecretRef = %+v", root.Accounts.App.Secret.Ref)
 	}
 	if got := root.Accounts.App.Tenant; got != "feishu" {
 		t.Errorf("Tenant = %q, want %q", got, "feishu")
@@ -92,8 +95,74 @@ func TestReadLarkChannelConfig_PartialFields(t *testing.T) {
 	if root.Accounts.App.ID != "" {
 		t.Errorf("expected empty ID, got %q", root.Accounts.App.ID)
 	}
-	if root.Accounts.App.Secret != "" {
-		t.Errorf("expected empty Secret, got %q", root.Accounts.App.Secret)
+	if !root.Accounts.App.Secret.IsZero() {
+		t.Errorf("expected zero Secret, got %+v", root.Accounts.App.Secret)
+	}
+}
+
+func TestReadLarkChannelConfig_SecretEnvTemplate(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "config.json")
+	data := `{"accounts":{"app":{"id":"cli_a","secret":"${LARK_APP_SECRET}","tenant":"feishu"}}}`
+	if err := os.WriteFile(p, []byte(data), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+	root, err := ReadLarkChannelConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got := root.Accounts.App.Secret.Plain; got != "${LARK_APP_SECRET}" {
+		t.Errorf("Secret.Plain = %q, want template string", got)
+	}
+}
+
+func TestReadLarkChannelConfig_SecretRefExec(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "config.json")
+	data := `{
+		"accounts": {
+			"app": {
+				"id": "cli_a",
+				"secret": {"source": "exec", "provider": "decrypt", "id": "app-cli_a"},
+				"tenant": "feishu"
+			}
+		},
+		"secrets": {
+			"providers": {
+				"decrypt": {"source": "exec", "command": "/usr/local/bin/lark-channel-bridge", "args": ["secrets", "get"]}
+			}
+		}
+	}`
+	if err := os.WriteFile(p, []byte(data), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+	root, err := ReadLarkChannelConfig(p)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if root.Accounts.App.Secret.Ref == nil {
+		t.Fatal("expected SecretRef, got Plain")
+	}
+	if got := root.Accounts.App.Secret.Ref.Source; got != "exec" {
+		t.Errorf("Secret.Ref.Source = %q, want %q", got, "exec")
+	}
+	if got := root.Accounts.App.Secret.Ref.ID; got != "app-cli_a" {
+		t.Errorf("Secret.Ref.ID = %q, want %q", got, "app-cli_a")
+	}
+	if root.Secrets == nil || root.Secrets.Providers["decrypt"] == nil {
+		t.Errorf("expected secrets.providers[decrypt] to be parsed")
+	}
+}
+
+func TestReadLarkChannelConfig_SecretRefInvalidSource(t *testing.T) {
+	dir := t.TempDir()
+	p := filepath.Join(dir, "config.json")
+	data := `{"accounts":{"app":{"id":"cli_a","secret":{"source":"bogus","id":"x"},"tenant":"feishu"}}}`
+	if err := os.WriteFile(p, []byte(data), 0o600); err != nil {
+		t.Fatalf("write temp file: %v", err)
+	}
+	if _, err := ReadLarkChannelConfig(p); err == nil {
+		t.Fatal("expected error for invalid secret source, got nil")
 	}
 }
 

package.json

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

shortcuts/doc/doc_media_insert.go

@@ -7,6 +7,11 @@ import (
 	"bytes"
 	"context"
 	"fmt"
+	"image"
+	_ "image/gif"
+	_ "image/jpeg"
+	_ "image/png"
+	"io"
 	"path/filepath"
 	"strings"
 
@@ -55,6 +60,8 @@ var DocMediaInsert = common.Shortcut{
 		{Name: "selection-with-ellipsis", Desc: "plain text (or 'start...end' to disambiguate) matching the target block's content. Media is inserted at the top-level ancestor of the matched block — i.e., when the selection is inside a callout, table cell, or nested list, media lands outside that container, not inside it. Pass 'start...end' (a unique prefix and suffix separated by '...') when the plain text appears in more than one block"},
 		{Name: "before", Type: "bool", Desc: "insert before the matched block instead of after (requires --selection-with-ellipsis)"},
 		{Name: "file-view", Desc: "file block rendering: card (default) | preview | inline; only applies when --type=file. preview renders audio/video as an inline player"},
+		{Name: "width", Type: "int", Desc: "image display width in pixels (only for --type=image); if --height is omitted it is auto-computed from the source image aspect ratio"},
+		{Name: "height", Type: "int", Desc: "image display height in pixels (only for --type=image); if --width is omitted it is auto-computed from the source image aspect ratio"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		filePath := runtime.Str("file")
@@ -93,6 +100,24 @@ var DocMediaInsert = common.Shortcut{
 				return output.ErrValidation("--file-view only applies when --type=file")
 			}
 		}
+		widthChanged := runtime.Changed("width")
+		heightChanged := runtime.Changed("height")
+		if (widthChanged || heightChanged) && runtime.Str("type") != "image" {
+			return output.ErrValidation("--width/--height only apply when --type=image")
+		}
+		if widthChanged && runtime.Int("width") <= 0 {
+			return output.ErrValidation("--width must be a positive integer")
+		}
+		if heightChanged && runtime.Int("height") <= 0 {
+			return output.ErrValidation("--height must be a positive integer")
+		}
+		const maxDimension = 10000
+		if widthChanged && runtime.Int("width") > maxDimension {
+			return output.ErrValidation("--width must not exceed %d pixels", maxDimension)
+		}
+		if heightChanged && runtime.Int("height") > maxDimension {
+			return output.ErrValidation("--height must not exceed %d pixels", maxDimension)
+		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -120,7 +145,25 @@ var DocMediaInsert = common.Shortcut{
 		} else {
 			createBlockData["index"] = "<children_len>"
 		}
-		batchUpdateData := buildBatchUpdateData("<new_block_id>", mediaType, "<file_token>", runtime.Str("align"), caption)
+		// Best-effort dimension computation for dry-run.
+		dryWidth := runtime.Int("width")
+		dryHeight := runtime.Int("height")
+		widthChanged := runtime.Changed("width")
+		heightChanged := runtime.Changed("height")
+
+		if (widthChanged || heightChanged) && !(widthChanged && heightChanged) {
+			if filePath == "<clipboard image>" {
+				fmt.Fprintf(runtime.IO().ErrOut, "Note: cannot detect clipboard image dimensions in dry-run; provide both --width and --height for accurate preview\n")
+			} else if nativeW, nativeH, err := detectImageDimensionsFromPath(runtime.FileIO(), filePath); err == nil {
+				dims := computeMissingDimension(dryWidth, dryHeight, nativeW, nativeH)
+				dryWidth = dims.width
+				dryHeight = dims.height
+			} else {
+				fmt.Fprintf(runtime.IO().ErrOut, "Note: unable to detect image dimensions from %s; provide both --width and --height to avoid failure at execution time\n", filePath)
+			}
+		}
+
+		batchUpdateData := buildBatchUpdateData("<new_block_id>", mediaType, "<file_token>", runtime.Str("align"), caption, dryWidth, dryHeight)
 
 		d := common.NewDryRunAPI()
 		totalSteps := 4
@@ -188,6 +231,9 @@ var DocMediaInsert = common.Shortcut{
 		if runtime.Bool("from-clipboard") {
 			d.Set("upload_size_note", "clipboard size unknown; single-part vs multipart decision deferred to runtime")
 		}
+		if runtime.Bool("from-clipboard") && (widthChanged || heightChanged) && !(widthChanged && heightChanged) {
+			d.Set("dimension_note", "clipboard dimensions unknown; aspect-ratio calculation deferred to runtime")
+		}
 		return d
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -314,6 +360,42 @@ var DocMediaInsert = common.Shortcut{
 		// interface stays a true nil for the --file path. Passing a typed-nil
 		// *bytes.Reader here would make the downstream `if cfg.Content != nil`
 		// check incorrectly take the clipboard branch and crash on Read.
+		// Resolve display dimensions before upload to fail fast on unreadable images.
+		var finalWidth, finalHeight int
+		if mediaType == "image" {
+			userWidth := runtime.Int("width")
+			userHeight := runtime.Int("height")
+			widthChanged := runtime.Changed("width")
+			heightChanged := runtime.Changed("height")
+
+			if widthChanged && heightChanged {
+				finalWidth = userWidth
+				finalHeight = userHeight
+			} else if widthChanged || heightChanged {
+				var nativeW, nativeH int
+				var dimErr error
+				if clipboardContent != nil {
+					nativeW, nativeH, dimErr = detectImageDimensions(bytes.NewReader(clipboardContent))
+				} else {
+					f, openErr := runtime.FileIO().Open(filePath)
+					if openErr != nil {
+						return withRollbackWarning(output.ErrValidation(
+							"unable to detect image dimensions from %s for aspect-ratio calculation; provide both --width and --height", fileName))
+					}
+					nativeW, nativeH, dimErr = detectImageDimensions(f)
+					f.Close()
+				}
+				if dimErr != nil {
+					return withRollbackWarning(output.ErrValidation(
+						"unable to detect image dimensions from %s for aspect-ratio calculation; provide both --width and --height", fileName))
+				}
+				dims := computeMissingDimension(userWidth, userHeight, nativeW, nativeH)
+				finalWidth = dims.width
+				finalHeight = dims.height
+				fmt.Fprintf(runtime.IO().ErrOut, "Image dimensions: %dx%d (native: %dx%d)\n", finalWidth, finalHeight, nativeW, nativeH)
+			}
+		}
+
 		uploadCfg := UploadDocMediaFileConfig{
 			FilePath:   filePath,
 			FileName:   fileName,
@@ -337,16 +419,23 @@ var DocMediaInsert = common.Shortcut{
 
 		if _, err := runtime.CallAPI("PATCH",
 			fmt.Sprintf("/open-apis/docx/v1/documents/%s/blocks/batch_update", validate.EncodePathSegment(documentID)),
-			nil, buildBatchUpdateData(replaceBlockID, mediaType, fileToken, alignStr, caption)); err != nil {
+			nil, buildBatchUpdateData(replaceBlockID, mediaType, fileToken, alignStr, caption, finalWidth, finalHeight)); err != nil {
 			return withRollbackWarning(err)
 		}
 
-		runtime.Out(map[string]interface{}{
+		outData := map[string]interface{}{
 			"document_id": documentID,
 			"block_id":    blockId,
 			"file_token":  fileToken,
 			"type":        mediaType,
-		}, nil)
+		}
+		if finalWidth > 0 {
+			outData["width"] = finalWidth
+		}
+		if finalHeight > 0 {
+			outData["height"] = finalHeight
+		}
+		runtime.Out(outData, nil)
 		return nil
 	},
 }
@@ -453,7 +542,51 @@ func resolveDocxDocumentID(runtime *common.RuntimeContext, input string) (string
 	}
 }
 
-func buildBatchUpdateData(blockID, mediaType, fileToken, alignStr, caption string) map[string]interface{} {
+type imageDimensions struct {
+	width  int
+	height int
+}
+
+func computeMissingDimension(userWidth, userHeight, nativeWidth, nativeHeight int) imageDimensions {
+	if nativeWidth <= 0 || nativeHeight <= 0 {
+		return imageDimensions{width: userWidth, height: userHeight}
+	}
+	if userWidth > 0 && userHeight == 0 {
+		return imageDimensions{
+			width:  userWidth,
+			height: (userWidth*nativeHeight + nativeWidth/2) / nativeWidth,
+		}
+	}
+	if userHeight > 0 && userWidth == 0 {
+		return imageDimensions{
+			width:  (userHeight*nativeWidth + nativeHeight/2) / nativeHeight,
+			height: userHeight,
+		}
+	}
+	return imageDimensions{width: userWidth, height: userHeight}
+}
+
+func detectImageDimensions(r io.Reader) (width, height int, err error) {
+	cfg, _, err := image.DecodeConfig(r)
+	if err != nil {
+		return 0, 0, err
+	}
+	return cfg.Width, cfg.Height, nil
+}
+
+func detectImageDimensionsFromPath(fio fileio.FileIO, filePath string) (int, int, error) {
+	if _, err := validate.SafeInputPath(filePath); err != nil {
+		return 0, 0, err
+	}
+	f, err := fio.Open(filePath)
+	if err != nil {
+		return 0, 0, err
+	}
+	defer f.Close()
+	return detectImageDimensions(f)
+}
+
+func buildBatchUpdateData(blockID, mediaType, fileToken, alignStr, caption string, width, height int) map[string]interface{} {
 	request := map[string]interface{}{
 		"block_id": blockID,
 	}
@@ -465,6 +598,12 @@ func buildBatchUpdateData(blockID, mediaType, fileToken, alignStr, caption strin
 		replaceImage := map[string]interface{}{
 			"token": fileToken,
 		}
+		if width > 0 {
+			replaceImage["width"] = width
+		}
+		if height > 0 {
+			replaceImage["height"] = height
+		}
 		if alignVal, ok := alignMap[alignStr]; ok {
 			replaceImage["align"] = alignVal
 		}

shortcuts/doc/doc_media_insert_test.go

@@ -6,6 +6,7 @@ package doc
 import (
 	"context"
 	"encoding/json"
+	"fmt"
 	"reflect"
 	"strings"
 	"testing"
@@ -176,7 +177,7 @@ func TestBuildDeleteBlockDataUsesHalfOpenInterval(t *testing.T) {
 func TestBuildBatchUpdateDataForImage(t *testing.T) {
 	t.Parallel()
 
-	got := buildBatchUpdateData("blk_1", "image", "file_tok", "center", "caption text")
+	got := buildBatchUpdateData("blk_1", "image", "file_tok", "center", "caption text", 0, 0)
 	want := map[string]interface{}{
 		"requests": []interface{}{
 			map[string]interface{}{
@@ -199,7 +200,7 @@ func TestBuildBatchUpdateDataForImage(t *testing.T) {
 func TestBuildBatchUpdateDataForFile(t *testing.T) {
 	t.Parallel()
 
-	got := buildBatchUpdateData("blk_2", "file", "file_tok", "", "")
+	got := buildBatchUpdateData("blk_2", "file", "file_tok", "", "", 0, 0)
 	want := map[string]interface{}{
 		"requests": []interface{}{
 			map[string]interface{}{
@@ -215,6 +216,48 @@ func TestBuildBatchUpdateDataForFile(t *testing.T) {
 	}
 }
 
+func TestBuildBatchUpdateDataForImageWithWidthHeight(t *testing.T) {
+	t.Parallel()
+
+	got := buildBatchUpdateData("blk_1", "image", "file_tok", "center", "caption text", 800, 447)
+	want := map[string]interface{}{
+		"requests": []interface{}{
+			map[string]interface{}{
+				"block_id": "blk_1",
+				"replace_image": map[string]interface{}{
+					"token":   "file_tok",
+					"width":   800,
+					"height":  447,
+					"align":   2,
+					"caption": map[string]interface{}{"content": "caption text"},
+				},
+			},
+		},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("buildBatchUpdateData(image, 800, 447) = %#v, want %#v", got, want)
+	}
+}
+
+func TestBuildBatchUpdateDataForFileIgnoresWidthHeight(t *testing.T) {
+	t.Parallel()
+
+	got := buildBatchUpdateData("blk_2", "file", "file_tok", "", "", 800, 600)
+	want := map[string]interface{}{
+		"requests": []interface{}{
+			map[string]interface{}{
+				"block_id": "blk_2",
+				"replace_file": map[string]interface{}{
+					"token": "file_tok",
+				},
+			},
+		},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("buildBatchUpdateData(file, 800, 600) = %#v, want %#v", got, want)
+	}
+}
+
 func TestExtractAppendTargetUsesRootChildrenCount(t *testing.T) {
 	t.Parallel()
 
@@ -669,10 +712,202 @@ func newMediaInsertValidateRuntime(t *testing.T, doc, mediaType, fileView string
 	return common.TestNewRuntimeContext(cmd, nil)
 }
 
-// Validate is the real user-facing contract for --file-view: unknown
-// values must be rejected, and passing the flag alongside --type!=file
-// must also be rejected. buildCreateBlockData tests alone cannot catch
-// regressions here, so lock the guard logic down explicitly.
+func newMediaInsertValidateRuntimeWithSize(t *testing.T, doc, mediaType string, width, height int, setWidth, setHeight bool) *common.RuntimeContext {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: "docs +media-insert"}
+	cmd.Flags().String("file", "", "")
+	cmd.Flags().Bool("from-clipboard", false, "")
+	cmd.Flags().String("doc", "", "")
+	cmd.Flags().String("type", "", "")
+	cmd.Flags().String("file-view", "", "")
+	cmd.Flags().Int("width", 0, "")
+	cmd.Flags().Int("height", 0, "")
+	cmd.Flags().String("selection-with-ellipsis", "", "")
+	cmd.Flags().Bool("before", false, "")
+	if err := cmd.Flags().Set("file", "dummy.bin"); err != nil {
+		t.Fatalf("set --file: %v", err)
+	}
+	if err := cmd.Flags().Set("doc", doc); err != nil {
+		t.Fatalf("set --doc: %v", err)
+	}
+	if err := cmd.Flags().Set("type", mediaType); err != nil {
+		t.Fatalf("set --type: %v", err)
+	}
+	if setWidth {
+		if err := cmd.Flags().Set("width", fmt.Sprintf("%d", width)); err != nil {
+			t.Fatalf("set --width: %v", err)
+		}
+	}
+	if setHeight {
+		if err := cmd.Flags().Set("height", fmt.Sprintf("%d", height)); err != nil {
+			t.Fatalf("set --height: %v", err)
+		}
+	}
+	return common.TestNewRuntimeContext(cmd, nil)
+}
+
+func TestDocMediaInsertValidateWidthHeightOnlyForImage(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		mediaType string
+		width     int
+		height    int
+		setWidth  bool
+		setHeight bool
+		wantErr   string
+	}{
+		{
+			name:      "width with file type is rejected",
+			mediaType: "file",
+			width:     800,
+			setWidth:  true,
+			wantErr:   "--width/--height only apply when --type=image",
+		},
+		{
+			name:      "height with file type is rejected",
+			mediaType: "file",
+			height:    600,
+			setHeight: true,
+			wantErr:   "--width/--height only apply when --type=image",
+		},
+		{
+			name:      "explicit zero width is rejected",
+			mediaType: "image",
+			width:     0,
+			setWidth:  true,
+			wantErr:   "--width must be a positive integer",
+		},
+		{
+			name:      "negative width is rejected",
+			mediaType: "image",
+			width:     -1,
+			setWidth:  true,
+			wantErr:   "--width must be a positive integer",
+		},
+		{
+			name:      "negative height is rejected",
+			mediaType: "image",
+			height:    -5,
+			setHeight: true,
+			wantErr:   "--height must be a positive integer",
+		},
+		{
+			name:      "valid width with image type is accepted",
+			mediaType: "image",
+			width:     800,
+			setWidth:  true,
+		},
+		{
+			name:      "valid width and height with image type is accepted",
+			mediaType: "image",
+			width:     800,
+			height:    600,
+			setWidth:  true,
+			setHeight: true,
+		},
+	}
+
+	for _, ttTemp := range tests {
+		tt := ttTemp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			rt := newMediaInsertValidateRuntimeWithSize(t, "doxcnValidateSize", tt.mediaType, tt.width, tt.height, tt.setWidth, tt.setHeight)
+			err := DocMediaInsert.Validate(context.Background(), rt)
+			if tt.wantErr == "" {
+				if err != nil {
+					t.Fatalf("Validate() unexpected error: %v", err)
+				}
+				return
+			}
+			if err == nil {
+				t.Fatalf("Validate() error = nil, want error containing %q", tt.wantErr)
+			}
+			if !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("Validate() error = %q, want substring %q", err.Error(), tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestDocMediaInsertValidateNoWidthHeightIsValid(t *testing.T) {
+	t.Parallel()
+
+	rt := newMediaInsertValidateRuntimeWithSize(t, "doxcnNoSize", "image", 0, 0, false, false)
+	err := DocMediaInsert.Validate(context.Background(), rt)
+	if err != nil {
+		t.Fatalf("Validate() unexpected error when neither --width nor --height passed: %v", err)
+	}
+}
+
+func TestAutoAspectRatioFromWidth(t *testing.T) {
+	t.Parallel()
+
+	// Native image: 1200x800 (3:2 ratio)
+	// User provides width=600 → expected height = 600 * 800 / 1200 = 400
+	got := computeMissingDimension(600, 0, 1200, 800)
+	wantWidth, wantHeight := 600, 400
+	if got.width != wantWidth || got.height != wantHeight {
+		t.Fatalf("computeMissingDimension(600, 0, 1200, 800) = (%d, %d), want (%d, %d)", got.width, got.height, wantWidth, wantHeight)
+	}
+}
+
+func TestAutoAspectRatioFromHeight(t *testing.T) {
+	t.Parallel()
+
+	// Native image: 1200x800 (3:2 ratio)
+	// User provides height=400 → expected width = 400 * 1200 / 800 = 600
+	got := computeMissingDimension(0, 400, 1200, 800)
+	wantWidth, wantHeight := 600, 400
+	if got.width != wantWidth || got.height != wantHeight {
+		t.Fatalf("computeMissingDimension(0, 400, 1200, 800) = (%d, %d), want (%d, %d)", got.width, got.height, wantWidth, wantHeight)
+	}
+}
+
+func TestComputeMissingDimensionBothProvided(t *testing.T) {
+	t.Parallel()
+	got := computeMissingDimension(800, 600, 1200, 900)
+	if got.width != 800 || got.height != 600 {
+		t.Fatalf("computeMissingDimension(800, 600, 1200, 900) = (%d, %d), want (800, 600)", got.width, got.height)
+	}
+}
+
+func TestComputeMissingDimensionNeitherProvided(t *testing.T) {
+	t.Parallel()
+	got := computeMissingDimension(0, 0, 1200, 900)
+	if got.width != 0 || got.height != 0 {
+		t.Fatalf("computeMissingDimension(0, 0, 1200, 900) = (%d, %d), want (0, 0)", got.width, got.height)
+	}
+}
+
+func TestComputeMissingDimensionZeroNativeWidth(t *testing.T) {
+	t.Parallel()
+	got := computeMissingDimension(600, 0, 0, 800)
+	if got.width != 600 || got.height != 0 {
+		t.Fatalf("computeMissingDimension(600, 0, 0, 800) = (%d, %d), want (600, 0)", got.width, got.height)
+	}
+}
+
+func TestComputeMissingDimensionZeroNativeHeight(t *testing.T) {
+	t.Parallel()
+	got := computeMissingDimension(0, 400, 1200, 0)
+	if got.width != 0 || got.height != 400 {
+		t.Fatalf("computeMissingDimension(0, 400, 1200, 0) = (%d, %d), want (0, 400)", got.width, got.height)
+	}
+}
+
+func TestComputeMissingDimensionRounding(t *testing.T) {
+	t.Parallel()
+	got := computeMissingDimension(999, 0, 1000, 333)
+	want := (999*333 + 500) / 1000
+	if got.height != want {
+		t.Fatalf("computeMissingDimension(999, 0, 1000, 333).height = %d, want %d (rounded)", got.height, want)
+	}
+}
+
 func TestDocMediaInsertValidateFileView(t *testing.T) {
 	t.Parallel()
 

shortcuts/drive/drive_push.go

@@ -275,7 +275,14 @@ var DrivePush = common.Shortcut{
 					skipped++
 					continue
 				}
-				token, version, upErr := drivePushUploadFile(ctx, runtime, localFile, entry.FileToken, folderToken)
+				parentToken, parentErr := drivePushEnsureParentToken(ctx, runtime, folderToken, rel, folderCache)
+				if parentErr != nil {
+					items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "failed", SizeBytes: localFile.Size, Error: parentErr.Error()})
+					failed++
+					uploadFailed = true
+					continue
+				}
+				token, version, upErr := drivePushUploadFile(ctx, runtime, localFile, entry.FileToken, parentToken)
 				if upErr != nil {
 					// Token contract on overwrite failure: an in-place
 					// overwrite preserves the file's token, so the
@@ -580,6 +587,10 @@ func drivePushEnsureFolder(ctx context.Context, runtime *common.RuntimeContext,
 	return token, nil
 }
 
+func drivePushEnsureParentToken(ctx context.Context, runtime *common.RuntimeContext, rootFolderToken, relPath string, folderCache map[string]string) (string, error) {
+	return drivePushEnsureFolder(ctx, runtime, rootFolderToken, drivePushParentRel(relPath), folderCache)
+}
+
 // drivePushUploadFile uploads (or overwrites) a single local file. When
 // existingToken is non-empty, the request adds the file_token form field to
 // trigger overwrite-with-version semantics on the backend; the response is

shortcuts/drive/drive_push_test.go

@@ -1296,6 +1296,130 @@ func TestDrivePushReusesExistingRemoteFolder(t *testing.T) {
 	}
 }
 
+// TestDrivePushOverwriteNestedFileUsesParentFolderToken verifies that
+// overwriting an existing nested remote file keeps parent_node aligned with
+// the file's actual parent folder instead of the root folder token.
+func TestDrivePushOverwriteNestedFileUsesParentFolderToken(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll(filepath.Join("local", "sub"), 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join("local", "sub", "keep.txt"), []byte("local"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"files": []interface{}{
+					map[string]interface{}{"token": "fld_existing_sub", "name": "sub", "type": "folder"},
+				},
+				"has_more": false,
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=fld_existing_sub",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"files": []interface{}{
+					map[string]interface{}{"token": "tok_keep_nested", "name": "keep.txt", "type": "file"},
+				},
+				"has_more": false,
+			},
+		},
+	})
+
+	uploadStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_all",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"file_token": "tok_keep_nested",
+				"version":    "v2",
+			},
+		},
+	}
+	reg.Register(uploadStub)
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--if-exists", "overwrite",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v\nstdout: %s", err, stdout.String())
+	}
+
+	body := decodeDriveMultipartBody(t, uploadStub)
+	if got := body.Fields["file_token"]; got != "tok_keep_nested" {
+		t.Fatalf("upload_all file_token = %q, want tok_keep_nested", got)
+	}
+	if got := body.Fields["parent_node"]; got != "fld_existing_sub" {
+		t.Fatalf("upload_all parent_node = %q, want fld_existing_sub", got)
+	}
+}
+
+func TestDrivePushOverwriteNestedFileReportsParentEnsureFailure(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll(filepath.Join("local", "sub"), 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join("local", "sub", "keep.txt"), []byte("local"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"files": []interface{}{
+					map[string]interface{}{"token": "tok_keep_nested", "name": "sub/keep.txt", "type": "file"},
+				},
+				"has_more": false,
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/create_folder",
+		Body: map[string]interface{}{
+			"code": 9999,
+			"msg":  "create parent failed",
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--if-exists", "overwrite",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected parent ensure failure\nstdout: %s", stdout.String())
+	}
+	if !strings.Contains(stdout.String(), `"action": "failed"`) || !strings.Contains(stdout.String(), "create parent failed") {
+		t.Fatalf("expected failed item with create_folder error, got: %s", stdout.String())
+	}
+}
+
 // TestDrivePushMirrorsEmptyDirectories confirms the gap codex review
 // flagged: a local directory with no files inside must still surface on
 // Drive as a created sub-folder, not be silently dropped because the

skills/lark-doc/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: lark-doc
-version: 2.0.0
-description: "飞书云文档 / Docx / 知识库 Wiki 文档（v2）：创建、打开、读取、获取、查看、总结、整理、改写、翻译、审阅和编辑飞书文档内容。当用户给出飞书文档 URL/token，或说查看/读取/打开某个文档、提取文档内容、总结文档、生成/创建文档、追加/替换/删除/移动内容、调整排版、插入或下载文档图片/附件/素材/画板缩略图时使用。文档内容中出现嵌入电子表格、多维表格、画板、引用或同步块时，也先用本 skill 读取和提取 token，再切到对应 skill 下钻。使用本 skill 时，docs +create、docs +fetch、docs +update 必须携带 --api-version v2；默认使用 DocxXML，也支持 Markdown。"
+description: "飞书云文档 / Docx / 知识库 Wiki 文档（v2）：创建、打开、读取、获取、查看、总结、整理、改写、翻译、审阅和编辑飞书文档内容。当用户给出飞书文档 URL/token，或说查看/读取/打开某个文档、提取文档内容、总结文档、生成/创建文档、追加/替换/删除/移动内容、调整排版、插入或下载文档图片/附件/素材/画板缩略图时使用。文档内容中出现嵌入电子表格、多维表格、需要将重要信息可视化为画板（含 SVG 画板）、引用或同步块时，也先用本 skill 读取和提取 token，再切到对应 skill 下钻。使用本 skill 时，docs +create、docs +fetch、docs +update 必须携带 --api-version v2；默认使用 DocxXML，也支持 Markdown。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -34,6 +33,8 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
 
 ## 快速决策
 - 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
+- 写文档时，重要信息（核心流程、架构、对比、风险、路线图、关键指标、因果关系）优先规划为画板，不要只用文字或表格承载
+- 新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读 `lark-whiteboard`；复杂图才由主 Agent 先建 `<whiteboard type="blank"></whiteboard>`，再启动 SubAgent 读取 `lark-whiteboard` 写入
 - 用户说"看一下文档里的图片/附件/素材""预览素材" → 用 `lark-cli docs +media-preview`
 - 用户明确说"下载素材" → 用 `lark-cli docs +media-download`
 - 如果目标是画板/whiteboard/画板缩略图 → 只能用 `lark-cli docs +media-download --type whiteboard`（不要用 `+media-preview`）

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

@@ -67,6 +67,12 @@ lark-cli docs +media-insert --doc doxcnXXX --file ./spec.pdf --type file
 
 # 图片对齐与描述（caption）
 lark-cli docs +media-insert --doc doxcnXXX --from-clipboard --align center --caption "架构图"
+
+# Insert image with explicit display width (height auto-computed from aspect ratio)
+lark-cli docs +media-insert --doc doxcnXXX --file ./banner.png --width 800 --align center
+
+# Insert image with explicit width and height
+lark-cli docs +media-insert --doc doxcnXXX --from-clipboard --width 800 --height 447 --caption "architecture diagram"
 ```
 
 ## 参数
@@ -79,6 +85,8 @@ lark-cli docs +media-insert --doc doxcnXXX --from-clipboard --align center --cap
 | `--type <type>` | 否 | `image`（默认）或 `file`。`--from-clipboard` 目前只产出 image。 |
 | `--align <align>` | 否 | 仅图片：`left` / `center`（默认）/ `right` |
 | `--caption <text>` | 否 | 仅图片：图片描述 |
+| `--width <px>` | 否 | Image display width in pixels (only for `--type=image`). If `--height` is omitted, it is auto-computed from the source image aspect ratio. Supported auto-detection formats: PNG, JPEG, GIF; other formats (WebP, BMP, etc.) require both `--width` and `--height`. |
+| `--height <px>` | 否 | Image display height in pixels (only for `--type=image`). If `--width` is omitted, it is auto-computed from the source image aspect ratio. Supported auto-detection formats: PNG, JPEG, GIF; other formats (WebP, BMP, etc.) require both `--width` and `--height`. |
 
 > [!IMPORTANT]
 > 如果上一步是 [`lark-doc-create`](lark-doc-create.md)，并且它在知识库/知识空间场景下返回的是 `/wiki/...` 形式的 `doc_url`，后续调用 `docs +media-insert` 时应优先传 `doc_id`，不要直接传这个 `doc_url`。

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

@@ -221,7 +221,7 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
 
 ## 画板处理
 
-> **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch --api-version v2` 取到 `<whiteboard token="...">`，再切到 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 用 `whiteboard +update` 写入。
+> **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch --api-version v2` 取到 `<whiteboard token="...">`，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 读取 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 并写入。
 
 画板的语法选型与插入示例见 [`lark-doc-style.md`](style/lark-doc-style.md) 的「画板语法与插入」章节。
 

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

@@ -6,46 +6,79 @@
 
 | Skill | 核心职责 | 约束 |
 |------|------|------|
-| `lark-doc` | 文档内容读取/更新、插入空白画板占位、获取 board_token | 不能直接编辑画板内容；`docs +update` 的画板能力仅限插入空白占位 |
-| `lark-whiteboard` | 查询/导出画板（+query）；图表内容生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入画板（+update） | 图表内容生成由此 skill 完整执行，不依赖外部调度 |
+| `lark-doc` | 识别画板机会、判断简单/复杂、调度 SubAgent、插入简单 SVG 画板或复杂空白画板 | 主 Agent 不直接创作画板内容；简单图不需要读取 `lark-whiteboard` |
+| `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板 | 仅复杂图或已有画板更新时由独立 SubAgent 读取 |
+
+## 画板优先规则
+
+写文档时，重要信息优先画板化。遇到核心流程、系统架构、方案对比、风险链路、里程碑、指标趋势、因果归因、组织关系、能力分层等内容，不要只用段落或表格承载；除非内容只是一次性补充说明，否则应规划为画板。
+
+同一篇文档可以有多个画板。优先多个聚焦画板，而不是把所有信息塞进一张大图。
 
 ## 文档与画板协同流程
 
-### 步骤 1：判断场景
+### 步骤 1：识别画板机会
 
 | 场景 | 入口 |
 |------|------|
-| 文档中需要插入新画板 | 继续步骤 2 |
-| 已有画板需要更新内容 | 先 `docs +fetch --api-version v2` 获取 `board_token`，跳至步骤 3 |
+| 文档中需要插入简单新画板 | 走步骤 2A |
+| 文档中需要插入复杂新画板 | 走步骤 2B |
+| 已有画板需要更新内容 | 先 `docs +fetch --api-version v2` 获取 `board_token`，跳至步骤 3B |
 | 只查看 / 下载已有画板 | 切换至 `lark-whiteboard`，不走本流程 |
 
-### 步骤 2：在文档中创建空白画板
+简单图判定：节点少、静态、布局可控、适合一个完整自包含 SVG 表达，例如小型流程、2-3 方对比、小型状态机、简单时间线或小型示意图。
 
-- 创建场景：`docs +create`；编辑场景：`docs +update`
-- markdown 中使用 `<whiteboard type="blank"></whiteboard>`（不要转义）
-- 多个画板时，在相应的地方插入各自的 whiteboard 标签
-- 从响应的 `data.board_tokens` 中读取 token 列表
+复杂图判定：节点多、跨泳道/跨系统、需要自动布局或精细排版、包含数据图表、组织架构、复杂架构、复杂依赖、已有画板更新，或需要 `lark-whiteboard` 的渲染验证。
 
-### 步骤 3：生成并写入画板内容
+### 步骤 2A：简单图 — SubAgent 直接插入 SVG 画板
 
-读取 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)，跳至"渲染 & 写入画板"章节，按其完整流程为每个 board_token 生成并写入图表内容。
+主 Agent 启动 SubAgent，让它用 `docs +create --api-version v2` / `docs +update --api-version v2` 插入：
 
-多个画板时依次处理，每个画板完成后再处理下一个。
+```xml
+<whiteboard type="svg"><svg ...>...</svg></whiteboard>
+```
+
+简单图 SubAgent 的最小上下文：
+- doc token、插入位置（标题 / block_id / command）
+- 图表目标、受众、源段落或数据
+- 要求读取 `lark-doc-xml.md`；不需要读取 `lark-whiteboard`
+- SVG 必须完整自包含：包含 `<svg>` 根节点和 `viewBox`，不引用外部图片、脚本、远程资源
+
+### 步骤 2B：复杂图 — 先创建空白画板
+
+- 主 Agent 使用 `docs +create --api-version v2` / `docs +update --api-version v2` 插入 `<whiteboard type="blank"></whiteboard>`。
+- 从 v2 响应的 `data.document.new_blocks[]` 中读取 `block_type == "whiteboard"` 的 `block_token` 作为 board_token。
+
+### 步骤 3B：复杂图或已有画板 — 启动 lark-whiteboard SubAgent
+
+复杂图和已有画板更新必须启动 SubAgent。主 Agent 只传最小上下文，不直接执行 `lark-whiteboard` 的渲染和写入流程。
+
+复杂图 SubAgent 的最小上下文：
+- board_token
+- 图表目标、推荐画板类型、受众
+- 与图表直接相关的源段落或数据
+- 要求读取 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)，按其完整流程写入该 board_token
+
+多个画板互不依赖时，可并行启动多个 SubAgent；每个 SubAgent 只负责一个画板或一个 SVG 插入点，不要互相复用上下文。
 
 ### 步骤 4：完成校验
 
-- 确认每个 token 对应的画板都已填充真实内容
-- 不保留空白占位画板；只有空白画板而无内容视为任务未完成
+- 简单 SVG：确认插入的是 `<whiteboard type="svg">`，且内容是完整 `<svg ...>...</svg>`
+- 复杂画板：确认每个 token 对应的画板都已填充真实内容
+- 不保留空白占位画板；复杂路径只有空白画板而无内容视为任务未完成
 
 ---
 
 ## 语义与画板类型映射
 
+下表用于帮助主 Agent 判断简单/复杂路径，并给 SubAgent 指定推荐画板类型。
+
 | 语义 | 画板类型 |
 |------|------|
-| 架构/分层/技术方案/模块依赖/调用关系 | 架构图 |
-| 流程/审批/部署/业务流转/状态机 | 流程图 |
-| 跨角色流程/跨系统交互/端到端链路 | 泳道图 |
+| 小型流程/状态机/简单时间线/小型对比/小型示意图 | SVG 画板（简单路径） |
+| 架构/分层/技术方案/模块依赖/调用关系 | 架构图（复杂路径） |
+| 流程/审批/部署/业务流转/状态机 | 流程图（按复杂度分流） |
+| 跨角色流程/跨系统交互/端到端链路 | 泳道图（复杂路径） |
 | 组织/层级/汇报关系 | 组织架构图 |
 | 时间线/里程碑/版本规划 | 里程碑图 |
 | 因果/复盘/根因分析 | 鱼骨图 |
@@ -56,6 +89,7 @@
 | 转化漏斗/销售漏斗 | 漏斗图 |
 | 分类梳理/知识体系/思维导图/时序图/类图 | Mermaid |
 | 数据分布/占比/饼图 | Mermaid |
+| 简单自定义图形/小型 SVG 示意图 | SVG 画板（简单路径） |
 | 柱状图/条形图/数据对比 | 柱状图 |
 | 折线图/趋势图/时序数据 | 折线图 |
 

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

@@ -15,7 +15,7 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 |-|-|-|
 | `<callout>` | 高亮框，子块仅支持文本、标题、列表、待办、引用 | `emoji`(默认 bulb), `background-color`, `border-color`, `text-color` |
 | `<grid>` + `<column>` | 分栏布局，各列 width-ratio 之和为 1 | `width-ratio` |
-| `<whiteboard>` | 嵌入画板 | `type`: `mermaid` \| `plantuml` \| `blank` |
+| `<whiteboard>` | 嵌入画板 | `type`: `blank` \| `mermaid` \| `plantuml` \| `svg` |
 | `<pre>` | （代码块，内含 `code`）| `lang`, `caption` |
 | `<figure>` | 视图容器 | `view-type` |
 | `<bookmark>` | 书签链接 | `<bookmark name="标题" href="https://..."></bookmark>`，必传 name 和 href |
@@ -41,7 +41,7 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 文档中可嵌入外部资源块（属于容器标签的特殊形式），需要额外语法创建：
 
 - `<img>` — `<img href="https://..."/>` 上传网络图片
-- `<whiteboard>` — `<whiteboard type="blank"></whiteboard>` 空白；`<whiteboard type="mermaid|plantuml">内容</whiteboard>` 带内容；
+- `<whiteboard>` — 简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整自包含 SVG</whiteboard>`；复杂图使用 `<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）
 - `<chat_card>` — `<chat_card chat-id="CHAT_ID"></chat_card>`，必传 chat-id
@@ -166,4 +166,4 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 
 <task task-id="TASK_GUID"></task>
 <chat_card chat-id="CHAT_ID"></chat_card>
-```
+```

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

@@ -19,7 +19,7 @@
 ### 第一波 — 规划与骨架（串行）
 
 1. 分析用户需求：受众、目的、范围
-2. 设计大纲——每个 h1/h2 章节至少规划 1 个非文本 block
+2. 设计大纲——每个 h1/h2 章节至少规划 1 个非文本 block；承载重要信息的章节优先规划画板
 3. `docs +create --api-version v2` **只建骨架**：标题 + 开头 `<callout>` + 各级标题 + 每节一句占位摘要
    - ⚠️ **不要**一次性把完整章节内容塞进 `--content`。超长 `--content` 容易触发字符/参数限制。
    - 完整内容留到第二波，由各 Agent 用 `docs +update --command append` 或 `block_insert_after` 分段写入。
@@ -35,11 +35,13 @@
 
 5. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果
 6. 评估样式达标（富 block 密度、元素多样性、连续 `<p>` 数量）
-7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。记录需要插图的章节及推荐的画板类型
+7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、简单/复杂路径和用于画图的源内容
 
-### 第四波 — 润色与图表（并行 Agent）
-8. Spawn Agent 定向改进：（结合 `lark-doc-style.md` 润色）
-   - **优先处理第三波识别出的画板需求**：简单图直接 `<whiteboard type="mermaid|plantuml">`，复杂图 spawn Agent 使用 **lark-whiteboard** skill
+### 第四波 — 画板与润色（并行 Agent）
+8. **优先处理第三波识别出的画板需求**：
+   - 简单图：启动 SVG SubAgent，直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；不读取 **lark-whiteboard**
+   - 复杂图：主 Agent 先插入 `<whiteboard type="blank"></whiteboard>` 并提取 `block_token`，再为每个 `block_token` 启动 SubAgent 使用 **lark-whiteboard** skill 写入画板
+9. Spawn 内容改写 Agent 定向润色：
    - 文字密集章节转为 `<table>`/`<grid>`/`<callout>`
    - 主要章节间补充 `<hr/>`
    - 本地图片使用 `docs +media-insert` 插入
@@ -47,4 +49,8 @@
 
 ## Agent 子任务要求
 
-Spawn Agent 时必须提供：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、具体的 `docs +update` command 和 `--block-id`。
+内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、具体的 `docs +update` command 和 `--block-id`。
+
+SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径。它只负责插入一个 `<whiteboard type="svg">...</whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。
+
+复杂画板 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。

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

@@ -8,26 +8,29 @@
 2. **Front-load 结论**：文档以 `<callout>` 开头概括核心结论；每章节首段点明要旨
 3. **视觉节奏**：连续纯文本不超过 3 段；不同主题章节间用 `<hr/>` 分隔
 4. **最少惊讶**：同类信息使用同类元素，全篇风格统一
+5. **重要信息画板化**：核心流程、架构、对比、风险、路线图、指标趋势等重要信息优先使用画板表达
 
 ## 二、元素选择指南
 
-涉及图表需求时，简单图用 `<whiteboard type="mermaid/plantuml">` 内嵌，复杂图使用 **lark-whiteboard** skill。
+涉及图表需求时，先判定简单/复杂：简单图启动 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读取 **lark-whiteboard**；复杂图才使用空白画板 + **lark-whiteboard** SubAgent。
 
-| 场景 | 推荐方案 |
-|-|-|
-| 核心结论 / 摘要 / 注意事项 | `<callout>` + emoji + 背景色 |
-| 方案对比 / 优劣势 / Before vs After | `<grid>` 2 列分栏 |
-| 3+ 属性的结构化数据 / 指标表 | `<table>` + 表头背景色 |
-| 任务清单 / 检查项 | `<checkbox>` |
-| 代码片段 | `<pre lang="x" caption="说明">` |
-| 引用 / 公式 | `<blockquote>` / `<latex>` |
-| 操作入口 / 跳转链接 | `<button>` / `<a type="url-preview">` |
-| 简单流程图 / 时序图 / 状态机 / 甘特图 | `<whiteboard type="mermaid/plantuml">` |
-| 复杂架构图 / 数据图 / 思维导图 / 组织架构 | **lark-whiteboard** skill |
+| 场景 | 推荐方案                                                          |
+|-|---------------------------------------------------------------|
+| 核心结论 / 摘要 / 注意事项 | `<callout>` + emoji + 背景色                                     |
+| 重要方案对比 / 优劣势 / Before vs After | `<grid>` 2 列分栏；简单 SVG SubAgent；复杂矩阵用 lark-whiteboard SubAgent |
+| 简短低风险对比 | `<grid>` 2 列分栏                                                |
+| 3+ 属性的结构化数据 / 指标表 | `<table>` + 表头背景色                                             |
+| 任务清单 / 检查项 | `<checkbox>`                                                  |
+| 代码片段 | `<pre lang="x" caption="说明">`                                 |
+| 引用 / 公式 | `<blockquote>` / `<latex>`                                    |
+| 操作入口 / 跳转链接 | `<button>` / `<a type="url-preview">`                         |
+| 简单流程图 / 小型状态机 / 小型时间线 | 简单 SVG SubAgent                                               |
+| 简单自定义图形 / 小型 SVG 示意图 | 简单 SVG SubAgent                                               |
+| 复杂架构图 / 数据图 / 思维导图 / 组织架构 | 空白画板 + lark-whiteboard SubAgent                               |
 
 ### 画板意图识别
 
-撰写或审查每个段落/章节时，**必须判断该内容是否适合用图表达**。满足以下任一特征时，应使用画板而非纯文本：
+撰写或审查每个段落/章节时，**必须判断该内容是否适合用图表达**。满足以下任一特征时，应使用画板而非纯文本；如果该内容承载章节核心结论、关键决策或主要论据，即使结构较简单也优先画板化：
 
 | 内容特征 | 信号词 / 模式 | 推荐画板类型 |
 |-|-|-|
@@ -45,21 +48,27 @@
 | 占比分布 | "占比"、"份额"、"分布"、百分比加总 ≈100% | 饼图 / 树状图 |
 
 **判断规则：**
-- 简单图（节点 ≤ 10、无需精细排版）→ `<whiteboard type="mermaid/plantuml">` 内嵌
-- 复杂图（节点 > 10、需自定义布局/样式、数据图表）→ spawn Agent 使用 **lark-whiteboard** skill
+- 重要信息能图示就图示；不要为了省步骤把关键流程、架构、对比、风险链路写成纯文本
+- 简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读取 **lark-whiteboard**
+- 复杂图或已有画板更新才先插入 `<whiteboard type="blank"></whiteboard>`，再启动 SubAgent 使用 **lark-whiteboard** skill 写入内容
+- 低重要度、局部辅助信息才用 `<table>` / `<grid>` / `<callout>` 承载
 
 ### 画板语法与插入
 
-> **提醒：** `docs +update` 不能编辑已有画板内容；下面的语法都是**新增**画板块。修改已有画板需切到 [`lark-whiteboard`](../../../lark-whiteboard/SKILL.md)。
+> **提醒：** `docs +update` 不能编辑已有画板内容；下面的语法都是**新增**画板块。修改已有画板需启动 SubAgent 读取 [`lark-whiteboard`](../../../lark-whiteboard/SKILL.md)。
 
-#### 内嵌 Mermaid / PlantUML（首选）
-简单图直接用 `<whiteboard type="mermaid|plantuml">语法</whiteboard>`，作为 block 嵌入文档。
+#### 简单 SVG 画板（SubAgent 插入）
 
-#### DSL 画板（Mermaid / PlantUML 不够用时）
-需要架构图、对比图、组织架构等复杂结构时：
-1. 用 `<whiteboard type="blank"></whiteboard>` 通过 `docs +create` / `docs +update` 插入空白画板
-2. 从响应 `data.document.new_blocks` 中提取画板 `block_token`
-3. 切到 [`lark-whiteboard`](../../../lark-whiteboard/SKILL.md) skill 设计并上传 DSL
+1. 主 Agent 启动 SubAgent，传入 doc token、插入位置、图表目标和源内容
+2. SubAgent 使用 `<whiteboard type="svg">完整自包含 SVG</whiteboard>` 通过 `docs +create --api-version v2` / `docs +update --api-version v2` 插入
+3. SVG 必须包含 `<svg>` 根节点和 `viewBox`，不要引用外部图片、脚本或远程资源
+
+#### 复杂画板（空白画板 + lark-whiteboard SubAgent）
+
+1. 用 `<whiteboard type="blank"></whiteboard>` 通过 `docs +create --api-version v2` / `docs +update --api-version v2` 插入空白画板
+2. 从 v2 响应 `data.document.new_blocks` 中提取画板 `block_token`
+3. 必须启动 SubAgent，把 `block_token`、图表目标、推荐画板类型和源内容交给它
+4. SubAgent 读取 [`lark-whiteboard`](../../../lark-whiteboard/SKILL.md) skill 并写入该画板；主 Agent 不直接调用画板渲染流程
 
 更完整的协同流程见 [`lark-doc-whiteboard.md`](../lark-doc-whiteboard.md)。
 

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

@@ -25,24 +25,30 @@
    - 用户明确要改整篇 → `docs +fetch --api-version v2 --detail with-ids`
    - 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) "意图引导：选择正确的 --scope"
 2. 系统性评估：结构清晰度、富 block 密度（≥40%）、元素多样性（≥3种）、连续 `<p>` 是否超过 3 段、是否有开头 callout 和章节 `<hr/>`
-3. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断哪些段落的信息适合用图表达。记录需要插图的章节（block ID）及推荐的画板类型
+3. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断哪些段落的信息适合用图表达。重要信息优先画板化，记录需要插图的章节（block ID）、推荐画板类型、简单/复杂路径和源内容片段
 4. 向用户简要说明改进计划（包含识别出的画板机会）
 
 ### 第二波 — 定向改写（并行 Agent）
 
-5. Spawn Agent 在不重叠的章节上并行改进，各 Agent 收到文档 token 和特定 block ID：（见 `lark-doc-style.md`）
+5. **优先处理第一波识别出的画板候选段落**：
+   - 简单图：启动 SVG SubAgent，直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；不读取 **lark-whiteboard**
+   - 复杂图：主 Agent 先插入 `<whiteboard type="blank"></whiteboard>` 并提取 `block_token`，再为每个 `block_token` 启动 SubAgent 使用 **lark-whiteboard** skill 写入画板
+6. Spawn 内容改写 Agent 在不重叠的章节上并行改进，各 Agent 收到文档 token 和特定 block ID：（见 `lark-doc-style.md`）
    - 开头适当添加 `<callout>`、重组引言
-   - 纯文本转为 `<grid>`/`<table>`/`<whiteboard>`
-   - **对第一波识别出的画板候选段落**：简单图直接 `<whiteboard type="mermaid|plantuml">`，复杂图 spawn Agent 使用 **lark-whiteboard** skill
-   - 添加流程图、对比分栏等富 block
+   - 纯文本转为 `<grid>`/`<table>`/`<callout>`
+   - 添加低重要度对比分栏、关键提示等富 block；画板类需求只走第 5 步
 
 ### 第三波 — 验证（串行）
 
-5. 获取更新后文档局部内容，重新检查样式指标
-6. 未达标则定向修正，向用户呈现结果
+7. 获取更新后文档局部内容，重新检查样式指标
+8. 未达标则定向修正，向用户呈现结果
 
 ## Agent 子任务要求
 
-Spawn Agent 时必须提供：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、具体的 `docs +update` command 和 `--block-id`。
+内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、具体的 `docs +update` command 和 `--block-id`。
+
+SVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径。它只负责插入一个 `<whiteboard type="svg">...</whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。
+
+复杂画板 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。
 
 **上下文节省提示**：Agent 如需在自己负责的章节内重新读取内容，优先用 `docs +fetch --api-version v2 --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉自己的章节，不要重复拉全文。

skills/lark-okr/references/lark-okr-entities.md

@@ -17,22 +17,6 @@ Alignment (对齐关系): Objective ↔ Objective
 Category (分类): Objective 的分组标签
 ```
 
-## 常用用户表述
-
-以下是部分用户可能会使用的指令表述，以及它们对应的实体与字段。
-
-- "进度 / 完成度 / 进展值"，当用户提到量化的进度或进展这样的概念时
-  - 对应实体: Indicator, 通常主要关注进度的当前值(Indicator.current_value)
-- "进展 / 更新 / Check-in"，当用户提到泛化的进度更新，尤其是有明确的文本化内容时
-  - 对应实体: Progress
-- "Objective 或 KeyResult 的状态"
-  - 对应字段: Indicator.indicator_status
-  - 注意，虽然 Objective/KeyResult 下的 Progress 中也有 ProgressRate 字段，但这一字段仅代表这条 Progress 的进度状态（创建 Progress 时的状态），而非 Objective/KeyResult 的当前进度
-- "打分 / 评分 / 分数"
-  - 对应字段: Objective.score, KeyResult.score, Cycle.score
-- "对齐 / 挂靠"
-  - 对应实体: Alignment
-
 ---
 
 ## Owner (所有者)

tests/cli_e2e/drive/drive_duplicate_sync_workflow_test.go

@@ -207,4 +207,69 @@ func TestDrive_DuplicateRemoteWorkflow(t *testing.T) {
 			t.Fatalf("+status should converge to a clean unchanged mirror\nstdout:\n%s", statusResult.Stdout)
 		}
 	})
+
+	t.Run("push overwrites nested remote file under its real parent", func(t *testing.T) {
+		suffix := clie2e.GenerateSuffix()
+		folderToken := createDriveFolder(t, parentT, ctx, "lark-cli-e2e-drive-nested-push-"+suffix, "")
+		subFolderToken := createDriveFolder(t, parentT, ctx, "sub", folderToken)
+
+		workDir := t.TempDir()
+		if err := os.MkdirAll(filepath.Join(workDir, "local", "sub"), 0o755); err != nil {
+			t.Fatalf("mkdir local/sub: %v", err)
+		}
+		if err := os.WriteFile(filepath.Join(workDir, "local", "sub", "keep.txt"), []byte("local-nested-overwrite"), 0o644); err != nil {
+			t.Fatalf("write local/sub/keep.txt: %v", err)
+		}
+
+		existingToken := uploadNamedFile(t, workDir, subFolderToken, "_nested_keep.txt", "keep.txt", "remote-before")
+
+		pushResult, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"drive", "+push",
+				"--local-dir", "local",
+				"--folder-token", folderToken,
+				"--if-exists", "overwrite",
+			},
+			WorkDir:   workDir,
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		pushResult.AssertExitCode(t, 0)
+		pushResult.AssertStdoutStatus(t, true)
+
+		if got := gjson.Get(pushResult.Stdout, "data.summary.uploaded").Int(); got != 1 {
+			t.Fatalf("nested +push uploaded=%d, want 1\nstdout:\n%s", got, pushResult.Stdout)
+		}
+		if got := gjson.Get(pushResult.Stdout, `data.items.#(rel_path="sub/keep.txt").action`).String(); got != "overwritten" {
+			t.Fatalf("nested +push action=%q, want overwritten\nstdout:\n%s", got, pushResult.Stdout)
+		}
+		if got := gjson.Get(pushResult.Stdout, `data.items.#(rel_path="sub/keep.txt").file_token`).String(); got != existingToken {
+			t.Fatalf("nested +push file_token=%q, want existing token %q\nstdout:\n%s", got, existingToken, pushResult.Stdout)
+		}
+
+		statusResult, err := clie2e.RunCmd(ctx, clie2e.Request{
+			Args: []string{
+				"drive", "+status",
+				"--local-dir", "local",
+				"--folder-token", folderToken,
+			},
+			WorkDir:   workDir,
+			DefaultAs: "bot",
+		})
+		require.NoError(t, err)
+		skipDriveStatusExactIfMissingDownloadScope(t, statusResult)
+		statusResult.AssertExitCode(t, 0)
+		statusResult.AssertStdoutStatus(t, true)
+		if got := gjson.Get(statusResult.Stdout, "data.unchanged.#").Int(); got != 1 {
+			t.Fatalf("nested +status unchanged count=%d, want 1\nstdout:\n%s", got, statusResult.Stdout)
+		}
+		if got := gjson.Get(statusResult.Stdout, "data.unchanged.0.rel_path").String(); got != "sub/keep.txt" {
+			t.Fatalf("nested +status unchanged rel_path=%q, want sub/keep.txt\nstdout:\n%s", got, statusResult.Stdout)
+		}
+		if got := gjson.Get(statusResult.Stdout, "data.modified.#").Int(); got != 0 ||
+			gjson.Get(statusResult.Stdout, "data.new_local.#").Int() != 0 ||
+			gjson.Get(statusResult.Stdout, "data.new_remote.#").Int() != 0 {
+			t.Fatalf("nested overwrite should converge to a clean unchanged mirror\nstdout:\n%s", statusResult.Stdout)
+		}
+	})
 }