docs: require hero imagery for svg slide roles

CHANGELOG.md

@@ -2,29 +2,6 @@
 
 All notable changes to this project will be documented in this file.
 
-## [v1.0.67] - 2026-07-08
-
-### Features
-
-- **mail**: add message modify and trash shortcuts (#1567)
-- support whiteboard file inputs in docs XML (#1784)
-- **vc**: refine meeting-events output and reaction forwarding (#1674)
-- **affordance**: usage guidance for shortcuts and per-command skills (#1793)
-
-### Bug Fixes
-
-- accept opaque wiki node tokens (#1789)
-- **apps**: make db --environment optional, auto-select branch server-side (#1735)
-- preserve original filename in multipart file upload (#1767)
-
-### Documentation
-
-- restore one-time authorization guidance in lark-apps skill (#1794)
-
-### Misc
-
-- e2e: harden CLI E2E retry, cleanup, and domain selection (#1709)
-
 ## [v1.0.66] - 2026-07-07
 
 ### Features
@@ -1421,7 +1398,6 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
-[v1.0.67]: https://github.com/larksuite/cli/releases/tag/v1.0.67
 [v1.0.66]: https://github.com/larksuite/cli/releases/tag/v1.0.66
 [v1.0.65]: https://github.com/larksuite/cli/releases/tag/v1.0.65
 [v1.0.64]: https://github.com/larksuite/cli/releases/tag/v1.0.64

affordance/README.md

@@ -10,33 +10,18 @@ step. Maintain these files alongside `skills/` and `shortcuts/`.
 A small, fixed markdown subset; each file describes one domain:
 
     # <domain>            optional `> skill: <name>` applies to every command below
-    ## <command>          the command as typed, minus `lark-cli <domain>`; a
-                          +-prefixed heading (## +create) targets that shortcut
+    ## <command>          the command as typed, minus `lark-cli <domain>`
     <lead paragraph>      when to use this command
     ### Avoid when        when not to use it / which command to use instead
     ### Prerequisites     what you must have first (e.g. an id, and where it comes from)
     ### Tips              gotchas and constraints
     ### Examples          **description** lines, each followed by a fenced command
-    ### Skills            bullet skill names, or name/relpath references
-                          (lark-contact/references/x.md), to read for usage;
-                          merged with the domain `> skill:` default (deduped,
-                          domain first)
     ### <other heading>   a custom section; flows through verbatim
 
 Reference another command with `[[command]]` — it renders as `command` in help.
 Under `Avoid when` it means "use that one instead"; under `Prerequisites`
 ("… from [[command]]") it means "get the input there first".
 
-Both service-API commands (`## messages get`) and `+`-prefixed shortcuts
-(`## +create`) take entries. A `### Skills` entry is a skill name (validated
-against `<name>/SKILL.md`) or a `name/relpath` reference into that skill
-(validated against the path); help drops any that don't resolve, so a typo shows
-nothing. Point a command at its own reference (e.g. `+search-user` →
-`lark-contact/references/lark-contact-search-user.md`) rather than re-listing the
-domain skill, which the `> skill:` default already covers. When a shortcut also
-sets a hand-authored `Tips` list in Go, the overlay's `### Tips` win — they
-replace the Go tips (not merged), so keep tips in one place.
-
 ## Example
 
     ## messages get
@@ -62,5 +47,3 @@ replace the Go tips (not merged), so keep tips in one place.
   anything the schema and flags already show; the agent infers the rest.
 - Command-form headings resolve to method ids via the registry, so plural resource
   names (`messages`) map to the singular method id (`message`) automatically.
-  `+`-prefixed shortcut headings are matched verbatim (no plural/space folding),
-  so the heading must equal the shortcut command exactly (`## +history-revert`).

affordance/contact.md

@@ -1,42 +1,6 @@
 # contact
 > skill: lark-contact
 
-## +search-user
-The primary user lookup for user identity: search by keyword or email, resolve known ids with --user-ids, or get yourself with --user-ids me — it does by-id reads too, so as a user you rarely need `+get-user`. Each match returns an open_id and p2p_chat_id to chain into follow-ups.
-
-### Skills
-- lark-contact/references/lark-contact-search-user.md
-
-### Avoid when
-- Running as a bot — this shortcut is user-only; use [[+get-user]] instead (it supports bot identity)
-- You only need users' personal status for ids you already hold → use [[user_profiles batch_query]]
-
-### Examples
-
-**Find a user by name**
-```bash
-lark-cli contact +search-user --query "alice" --as user
-```
-
-**Fetch known users by open_id (me = yourself)**
-```bash
-lark-cli contact +search-user --user-ids "ou_3a8b****6a7b,me" --as user
-```
-
-## +get-user
-Fetch one user's profile by id, or your own with --user-id omitted. Use it under bot identity — `+search-user` is user-only.
-
-### Skills
-- lark-contact/references/lark-contact-get-user.md
-
-### Avoid when
-- You don't have the user's id yet, or want to match by name/keyword → use [[+search-user]]
-- Running as a user — [[+search-user]] --user-ids covers by-id reads and more in one tool
-
-### Tips
-- Self lookup (omit --user-id) needs user identity; a bot must pass --user-id
-- --user-id-type must match the id you pass (default open_id)
-
 ## user_profiles batch_query
 Bulk-fetch personal status and signature for user ids you already have.
 

cmd/api/api_test.go

@@ -4,14 +4,10 @@
 package api
 
 import (
-	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
-	"mime"
-	"mime/multipart"
 	"os"
-	"path/filepath"
 	"sort"
 	"strings"
 	"testing"
@@ -1073,157 +1069,3 @@ func TestApiCmd_JsonFlag_Accepted(t *testing.T) {
 		t.Errorf("expected method GET, got %s", gotOpts.Method)
 	}
 }
-
-// parseMultipartFilenames drives one api --file upload through the mock
-// transport and returns a map of field name -> part filename parsed from the
-// captured multipart body, plus the map of text form fields. It fails the test
-// if the captured request is not multipart/form-data.
-func parseMultipartFilenames(t *testing.T, stub *httpmock.Stub) (map[string]string, map[string]string) {
-	t.Helper()
-	ct := stub.CapturedHeaders.Get("Content-Type")
-	mediaType, params, err := mime.ParseMediaType(ct)
-	if err != nil {
-		t.Fatalf("parse Content-Type %q: %v", ct, err)
-	}
-	if !strings.HasPrefix(mediaType, "multipart/") {
-		t.Fatalf("Content-Type = %q, want multipart/*", mediaType)
-	}
-	filenames := map[string]string{}
-	fields := map[string]string{}
-	mr := multipart.NewReader(bytes.NewReader(stub.CapturedBody), params["boundary"])
-	for {
-		part, err := mr.NextPart()
-		if err != nil {
-			break
-		}
-		if fn := part.FileName(); fn != "" {
-			filenames[part.FormName()] = fn
-		} else {
-			buf := &bytes.Buffer{}
-			_, _ = buf.ReadFrom(part)
-			fields[part.FormName()] = buf.String()
-		}
-	}
-	return filenames, fields
-}
-
-func TestApiCmd_FileUpload_PreservesFilename(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	dir := t.TempDir()
-	cmdutil.TestChdir(t, dir)
-	if err := os.WriteFile(filepath.Join(dir, "invoice.pdf"), []byte("%PDF-1.4 fake"), 0600); err != nil {
-		t.Fatalf("write test file: %v", err)
-	}
-
-	stub := &httpmock.Stub{
-		URL:  "/open-apis/approval/v4/files/upload",
-		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"code": "file_xxx"}},
-	}
-	reg.Register(stub)
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"POST", "/open-apis/approval/v4/files/upload", "--as", "bot", "--file", "invoice.pdf"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	filenames, _ := parseMultipartFilenames(t, stub)
-	if got := filenames["file"]; got != "invoice.pdf" {
-		t.Fatalf("part filename for field %q = %q, want %q", "file", got, "invoice.pdf")
-	}
-}
-
-func TestApiCmd_FileUpload_FieldPrefixKeepsBasename(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	dir := t.TempDir()
-	cmdutil.TestChdir(t, dir)
-	if err := os.MkdirAll(filepath.Join(dir, "sub"), 0700); err != nil {
-		t.Fatalf("mkdir: %v", err)
-	}
-	if err := os.WriteFile(filepath.Join(dir, "sub", "invoice.pdf"), []byte("%PDF-1.4 fake"), 0600); err != nil {
-		t.Fatalf("write test file: %v", err)
-	}
-
-	stub := &httpmock.Stub{
-		URL:  "/open-apis/approval/v4/files/upload",
-		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"code": "file_xxx"}},
-	}
-	reg.Register(stub)
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"POST", "/open-apis/approval/v4/files/upload", "--as", "bot", "--file", "upload=sub/invoice.pdf"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	filenames, _ := parseMultipartFilenames(t, stub)
-	if _, ok := filenames["upload"]; !ok {
-		t.Fatalf("expected field name %q from field=path form, got fields %v", "upload", filenames)
-	}
-	if got := filenames["upload"]; got != "invoice.pdf" {
-		t.Fatalf("part filename for field %q = %q, want %q (basename only)", "upload", got, "invoice.pdf")
-	}
-}
-
-func TestApiCmd_FileUpload_WithDataFields(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-
-	dir := t.TempDir()
-	cmdutil.TestChdir(t, dir)
-	if err := os.WriteFile(filepath.Join(dir, "invoice.pdf"), []byte("%PDF-1.4 fake"), 0600); err != nil {
-		t.Fatalf("write test file: %v", err)
-	}
-
-	stub := &httpmock.Stub{
-		URL:  "/open-apis/approval/v4/files/upload",
-		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"code": "file_xxx"}},
-	}
-	reg.Register(stub)
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"POST", "/open-apis/approval/v4/files/upload", "--as", "bot",
-		"--file", "invoice.pdf", "--data", `{"type":"attachment"}`})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	filenames, fields := parseMultipartFilenames(t, stub)
-	if got := filenames["file"]; got != "invoice.pdf" {
-		t.Fatalf("part filename = %q, want %q", got, "invoice.pdf")
-	}
-	if got := fields["type"]; got != "attachment" {
-		t.Fatalf("text field type = %q, want %q", got, "attachment")
-	}
-}
-
-func TestApiCmd_FileUpload_StdinFallsBackToUnknown(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{
-		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
-	})
-	f.IOStreams.In = bytes.NewReader([]byte("stdin-bytes"))
-
-	stub := &httpmock.Stub{
-		URL:  "/open-apis/approval/v4/files/upload",
-		Body: map[string]interface{}{"code": 0, "msg": "success", "data": map[string]interface{}{"code": "file_xxx"}},
-	}
-	reg.Register(stub)
-
-	cmd := NewCmdApi(f, nil)
-	cmd.SetArgs([]string{"POST", "/open-apis/approval/v4/files/upload", "--as", "bot", "--file", "-"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	filenames, _ := parseMultipartFilenames(t, stub)
-	if got := filenames["file"]; got != "unknown-file" {
-		t.Fatalf("stdin part filename = %q, want %q (no stable local name, fallback)", got, "unknown-file")
-	}
-}

cmd/root.go

@@ -679,11 +679,7 @@ func installTipsHelpFunc(root *cobra.Command) {
 			defaultHelp(cmd, args)
 			return
 		}
-		if service.PrepareMethodHelp(cmd, embeddedSkillContent) {
-			defaultHelp(cmd, args)
-			return
-		}
-		if service.PrepareShortcutHelp(cmd, embeddedSkillContent) {
+		if service.PrepareMethodHelp(cmd) {
 			defaultHelp(cmd, args)
 			return
 		}

cmd/service/affordance.go

@@ -71,18 +71,11 @@ func PrepareDomainHelp(cmd *cobra.Command, skillFS fs.FS) bool {
 }
 
 // domainHelpBase returns the description to seed domain help with — the
-// hand-authored Long when present, else the Short.
+// hand-authored Long when present, else the Short — captured once into an
+// annotation so re-rendering reuses the pristine text instead of the
+// already-augmented Long.
 func domainHelpBase(cmd *cobra.Command) string {
-	return captureHelpBase(cmd, domainBaseAnnotation)
-}
-
-// captureHelpBase records a command's pristine lead text once — its
-// hand-authored Long, or Short when Long is empty — into the given annotation,
-// so lazy re-renders compose onto the original text instead of onto an
-// already-augmented Long. This is what lets a shortcut's PostMount-authored
-// Long survive: it becomes the base the affordance block is appended below.
-func captureHelpBase(cmd *cobra.Command, key string) string {
-	if base, ok := cmd.Annotations[key]; ok {
+	if base, ok := cmd.Annotations[domainBaseAnnotation]; ok {
 		return base
 	}
 	base := cmd.Long
@@ -92,7 +85,7 @@ func captureHelpBase(cmd *cobra.Command, key string) string {
 	if cmd.Annotations == nil {
 		cmd.Annotations = map[string]string{}
 	}
-	cmd.Annotations[key] = base
+	cmd.Annotations[domainBaseAnnotation] = base
 	return base
 }
 
@@ -108,12 +101,12 @@ func methodLong(description, schemaPath, paramsOnly string) string {
 }
 
 // Annotation keys PrepareMethodHelp reads to rebuild a method command's Long.
-// The affordance overlay coordinates live in cmdmeta (shared with shortcuts).
 const (
-	schemaPathAnnotation   = "method-schema-path"
-	paramsOnlyAnnotation   = "method-params-only"
-	domainBaseAnnotation   = "affordance-domain-base"
-	shortcutBaseAnnotation = "affordance-shortcut-base"
+	affordanceServiceAnnotation = "affordance-service"
+	affordanceMethodAnnotation  = "affordance-method"
+	schemaPathAnnotation        = "method-schema-path"
+	paramsOnlyAnnotation        = "method-params-only"
+	domainBaseAnnotation        = "affordance-domain-base"
 )
 
 // setMethodHelpData records the coordinates PrepareMethodHelp needs (storing a
@@ -122,7 +115,10 @@ func setMethodHelpData(cmd *cobra.Command, service, methodID, schemaPath, params
 	if cmd.Annotations == nil {
 		cmd.Annotations = map[string]string{}
 	}
-	cmdmeta.SetAffordanceRef(cmd, service, methodID)
+	if service != "" && methodID != "" {
+		cmd.Annotations[affordanceServiceAnnotation] = service
+		cmd.Annotations[affordanceMethodAnnotation] = methodID
+	}
 	cmd.Annotations[schemaPathAnnotation] = schemaPath
 	if paramsOnly != "" {
 		cmd.Annotations[paramsOnlyAnnotation] = paramsOnly
@@ -132,11 +128,8 @@ func setMethodHelpData(cmd *cobra.Command, service, methodID, schemaPath, params
 // PrepareMethodHelp rebuilds a generated method command's Long with the agent
 // guidance at the TOP (Risk, then the affordance block, then the schema
 // pointer), returning false for non-method commands. The overlay is parsed
-// here — only when help is rendered. skillFS (nil-safe) gates the related-skill
-// pointers: each is emitted only when it resolves in the skill tree (see
-// affordance.SkillStatPath), so a typo or a build without embedded skills never
-// prints a `skills read` that cannot be opened.
-func PrepareMethodHelp(cmd *cobra.Command, skillFS fs.FS) bool {
+// here — only when help is rendered.
+func PrepareMethodHelp(cmd *cobra.Command) bool {
 	ann := cmd.Annotations
 	if ann == nil {
 		return false
@@ -148,15 +141,22 @@ func PrepareMethodHelp(cmd *cobra.Command, skillFS fs.FS) bool {
 
 	var b strings.Builder
 	b.WriteString(cmd.Short)
-	writeRisk(&b, cmd)
+	if level, ok := cmdutil.GetRisk(cmd); ok {
+		// --yes asserts the USER confirmed; the agent must not self-approve.
+		if level == cmdutil.RiskHighRiskWrite {
+			fmt.Fprintf(&b, "\n\nRisk: %s (requires explicit user confirmation to execute; the agent must NOT add --yes on its own — only pass --yes after the user has confirmed)", level)
+		} else {
+			fmt.Fprintf(&b, "\n\nRisk: %s", level)
+		}
+	}
 
 	var skills []string
 	if raw, ok := affordanceRaw(cmd); ok {
+		if block := renderAffordance(meta.Method{Affordance: raw}); block != "" {
+			b.WriteString("\n\n")
+			b.WriteString(block)
+		}
 		if a, ok := (meta.Method{Affordance: raw}).ParsedAffordance(); ok {
-			if block := renderAffordanceValue(a); block != "" {
-				b.WriteString("\n\n")
-				b.WriteString(block)
-			}
 			skills = a.Skills
 		}
 	}
@@ -164,93 +164,15 @@ func PrepareMethodHelp(cmd *cobra.Command, skillFS fs.FS) bool {
 	fmt.Fprintf(&b, "\n\nFull parameter schema:\n  lark-cli schema %s", schemaPath)
 	b.WriteString(ann[paramsOnlyAnnotation])
 
-	writeRelatedSkills(&b, skills, skillFS)
-
-	cmd.Long = b.String()
-	return true
-}
-
-// PrepareShortcutHelp composes a +-prefixed shortcut's Long from its affordance
-// overlay — the same top layout as method help (description, Risk, guidance
-// block, related skills) minus the schema pointer, which shortcuts have none
-// of. Returns false when the command is not a shortcut or carries no overlay
-// entry, so shortcuts without guidance keep the default help plus the bottom
-// risk/tips append.
-//
-// The lead is the command's pristine base (captureHelpBase): a shortcut that
-// set a hand-authored Long in PostMount (e.g. the docs shortcuts' "agents MUST
-// read the skill" directive) keeps it — the affordance block is appended below,
-// never clobbering it.
-//
-// Tips precedence (intentional, not a bug): the overlay's ### Tips win. The
-// shortcut's declarative Tips (the Go Tips field) are only a fallback used when
-// the overlay declares none; when the overlay has tips, the Go tips are dropped
-// (replaced, not merged) so tips never render twice. Authoring a ### Tips block
-// therefore silently retires that shortcut's Go Tips — consolidate into one.
-func PrepareShortcutHelp(cmd *cobra.Command, skillFS fs.FS) bool {
-	if src, _ := cmdmeta.SourceOf(cmd); src != cmdmeta.SourceShortcut {
-		return false
-	}
-	raw, ok := affordanceRaw(cmd)
-	if !ok {
-		return false
-	}
-	a, ok := (meta.Method{Affordance: raw}).ParsedAffordance()
-	if !ok {
-		return false
-	}
-	if len(a.Tips) == 0 {
-		a.Tips = cmdutil.GetTips(cmd)
-	}
-
-	var b strings.Builder
-	b.WriteString(captureHelpBase(cmd, shortcutBaseAnnotation))
-	writeRisk(&b, cmd)
-	if block := renderAffordanceValue(a); block != "" {
-		b.WriteString("\n\n")
-		b.WriteString(block)
-	}
-	writeRelatedSkills(&b, a.Skills, skillFS)
-
-	cmd.Long = b.String()
-	return true
-}
-
-// writeRisk appends the "Risk: <level>" line, warning agents not to self-approve
-// high-risk-write commands. A no-op when the command has no risk annotation.
-func writeRisk(b *strings.Builder, cmd *cobra.Command) {
-	level, ok := cmdutil.GetRisk(cmd)
-	if !ok {
-		return
-	}
-	// --yes asserts the USER confirmed; the agent must not self-approve.
-	if level == cmdutil.RiskHighRiskWrite {
-		fmt.Fprintf(b, "\n\nRisk: %s (requires explicit user confirmation to execute; the agent must NOT add --yes on its own — only pass --yes after the user has confirmed)", level)
-	} else {
-		fmt.Fprintf(b, "\n\nRisk: %s", level)
-	}
-}
-
-// writeRelatedSkills appends the "Related skills" block for the entries that
-// exist in skillFS. Nothing is written when skillFS is nil or no entry resolves,
-// so help never prints a `skills read` pointer that cannot be opened.
-func writeRelatedSkills(b *strings.Builder, skills []string, skillFS fs.FS) {
-	if skillFS == nil || len(skills) == 0 {
-		return
-	}
-	var avail []string
-	for _, s := range skills {
-		if _, err := fs.Stat(skillFS, affordance.SkillStatPath(s)); err == nil {
-			avail = append(avail, s)
+	if len(skills) > 0 {
+		b.WriteString("\n\nWorkflow skill (end-to-end usage):")
+		for _, s := range skills {
+			fmt.Fprintf(&b, "\n  lark-cli skills read %s", s)
 		}
 	}
-	if len(avail) == 0 {
-		return
-	}
-	b.WriteString("\n\nRelated skills (read for end-to-end usage):")
-	for _, s := range avail {
-		fmt.Fprintf(b, "\n  lark-cli skills read %s", s)
-	}
+
+	cmd.Long = b.String()
+	return true
 }
 
 // affordanceLookup is the overlay source; a package var so tests can inject.
@@ -267,8 +189,12 @@ func RenderAffordanceForCmd(cmd *cobra.Command) string {
 }
 
 func affordanceRaw(cmd *cobra.Command) (json.RawMessage, bool) {
-	service, methodID, ok := cmdmeta.AffordanceRef(cmd)
-	if !ok {
+	if cmd.Annotations == nil {
+		return nil, false
+	}
+	service := cmd.Annotations[affordanceServiceAnnotation]
+	methodID := cmd.Annotations[affordanceMethodAnnotation]
+	if service == "" || methodID == "" {
 		return nil, false
 	}
 	return affordanceLookup(service, methodID)
@@ -281,13 +207,7 @@ func renderAffordance(m meta.Method) string {
 	if !ok {
 		return ""
 	}
-	return renderAffordanceValue(a)
-}
 
-// renderAffordanceValue renders an already-parsed affordance. Split from
-// renderAffordance so callers can render a value they have adjusted first (e.g.
-// a shortcut folding its declarative tips into an overlay that has none).
-func renderAffordanceValue(a meta.Affordance) string {
 	var sections []string
 	bullets := func(title string, items []string) {
 		var nonEmpty []string

cmd/service/affordance_test.go

@@ -7,7 +7,6 @@ import (
 	"encoding/json"
 	"strings"
 	"testing"
-	"testing/fstest"
 
 	"github.com/larksuite/cli/internal/cmdmeta"
 	"github.com/larksuite/cli/internal/cmdutil"
@@ -71,8 +70,8 @@ func TestServiceMethod_AffordanceNotInLong(t *testing.T) {
 		t.Errorf("affordance must not be baked into Long (lazy):\n%s", cmd.Long)
 	}
 	// The lookup ref is recorded so the help path can resolve it later.
-	if svc, method, ok := cmdmeta.AffordanceRef(cmd); !ok || svc != "im" || method != "messages.create" {
-		t.Errorf("affordance ref = %q/%q (ok=%v), want im/messages.create", svc, method, ok)
+	if cmd.Annotations[affordanceServiceAnnotation] != "im" || cmd.Annotations[affordanceMethodAnnotation] != "messages.create" {
+		t.Errorf("affordance ref annotations = %v, want im/messages.create", cmd.Annotations)
 	}
 }
 
@@ -120,7 +119,7 @@ func TestPrepareMethodHelp(t *testing.T) {
 	m := map[string]interface{}{"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "发送消息"}
 	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(m), "create", "messages", nil)
 
-	if !PrepareMethodHelp(cmd, nil) {
+	if !PrepareMethodHelp(cmd) {
 		t.Fatal("PrepareMethodHelp returned false for a service-method command")
 	}
 	long := cmd.Long
@@ -137,133 +136,11 @@ func TestPrepareMethodHelp(t *testing.T) {
 	}
 
 	// A non-service command (no schema-path annotation) is left untouched.
-	if PrepareMethodHelp(&cobra.Command{Use: "plain"}, nil) {
+	if PrepareMethodHelp(&cobra.Command{Use: "plain"}) {
 		t.Error("PrepareMethodHelp should return false for a non-service command")
 	}
 }
 
-// PrepareShortcutHelp composes a shortcut's Long from its overlay with the same
-// top layout as method help (no schema pointer), folding declarative tips when
-// the overlay declares none, and leaves shortcuts without an overlay entry (and
-// non-shortcut commands) for the default help path.
-func TestPrepareShortcutHelp(t *testing.T) {
-	orig := affordanceLookup
-	t.Cleanup(func() { affordanceLookup = orig })
-	affordanceLookup = func(service, methodID string) (json.RawMessage, bool) {
-		if service == "calendar" && methodID == "+create" {
-			return json.RawMessage(`{"use_when":["高层创建日程"],"skills":["lark-calendar"]}`), true
-		}
-		return nil, false
-	}
-
-	sc := &cobra.Command{Use: "+create", Short: "Create an event"}
-	cmdmeta.SetSource(sc, cmdmeta.SourceShortcut, false)
-	cmdmeta.SetAffordanceRef(sc, "calendar", "+create")
-	cmdutil.SetRisk(sc, "write")
-	cmdutil.SetTips(sc, []string{"start/end 收 ISO 8601"})
-
-	if !PrepareShortcutHelp(sc, nil) {
-		t.Fatal("PrepareShortcutHelp returned false for a shortcut with an overlay")
-	}
-	for _, want := range []string{"Create an event", "Risk: write", "When to use:", "高层创建日程", "Tips:", "start/end 收 ISO 8601"} {
-		if !strings.Contains(sc.Long, want) {
-			t.Errorf("shortcut Long missing %q:\n%s", want, sc.Long)
-		}
-	}
-	if strings.Contains(sc.Long, "Full parameter schema:") {
-		t.Errorf("shortcut Long must not carry a schema pointer:\n%s", sc.Long)
-	}
-
-	// No overlay entry -> leave it for the default help path.
-	bare := &cobra.Command{Use: "+bare", Short: "x"}
-	cmdmeta.SetSource(bare, cmdmeta.SourceShortcut, false)
-	cmdmeta.SetAffordanceRef(bare, "calendar", "+bare")
-	if PrepareShortcutHelp(bare, nil) {
-		t.Error("PrepareShortcutHelp should return false when the shortcut has no overlay")
-	}
-
-	// Non-shortcut source is ignored even with a ref.
-	notSc := &cobra.Command{Use: "create", Short: "x"}
-	cmdmeta.SetAffordanceRef(notSc, "calendar", "+create")
-	if PrepareShortcutHelp(notSc, nil) {
-		t.Error("PrepareShortcutHelp should return false for a non-shortcut command")
-	}
-}
-
-// Related-skill pointers are gated on existence: a skill that resolves in the
-// skill FS renders, a typo is dropped (never print an unopenable `skills read`),
-// and a nil skill FS suppresses the whole block.
-func TestRelatedSkillsStatGating(t *testing.T) {
-	orig := affordanceLookup
-	t.Cleanup(func() { affordanceLookup = orig })
-	affordanceLookup = func(_, _ string) (json.RawMessage, bool) {
-		return json.RawMessage(`{"use_when":["x"],"skills":["lark-real","lark-typo","lark-real/references/deep.md","lark-real/references/missing.md"]}`), true
-	}
-	skillFS := fstest.MapFS{
-		"lark-real/SKILL.md":           {Data: []byte("# real")},
-		"lark-real/references/deep.md": {Data: []byte("# deep")},
-	}
-
-	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
-	m := map[string]interface{}{"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "d"}
-
-	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(m), "create", "messages", nil)
-	if !PrepareMethodHelp(cmd, skillFS) {
-		t.Fatal("PrepareMethodHelp returned false")
-	}
-	if !strings.Contains(cmd.Long, "skills read lark-real\n") {
-		t.Errorf("existing bare-name skill should render on its own line; got:\n%s", cmd.Long)
-	}
-	if strings.Contains(cmd.Long, "lark-typo") {
-		t.Errorf("nonexistent skill must be dropped, not printed as an unopenable pointer; got:\n%s", cmd.Long)
-	}
-	// A name/relpath reference to an existing file renders; a missing one drops.
-	if !strings.Contains(cmd.Long, "skills read lark-real/references/deep.md") {
-		t.Errorf("existing reference entry should render; got:\n%s", cmd.Long)
-	}
-	if strings.Contains(cmd.Long, "references/missing.md") {
-		t.Errorf("nonexistent reference must be dropped; got:\n%s", cmd.Long)
-	}
-
-	// nil skill FS: the whole Related-skills block is suppressed.
-	bare := NewCmdServiceMethod(f, imSpec(), meta.FromMap(m), "create", "messages", nil)
-	PrepareMethodHelp(bare, nil)
-	if strings.Contains(bare.Long, "Related skills") {
-		t.Errorf("nil skillFS should suppress the skills block; got:\n%s", bare.Long)
-	}
-}
-
-// A shortcut that set a hand-authored Long (as the docs shortcuts do in
-// PostMount) keeps it as the lead: the affordance block is appended below, not
-// clobbered, and re-rendering does not double-append.
-func TestPrepareShortcutHelp_PreservesPostMountLong(t *testing.T) {
-	orig := affordanceLookup
-	t.Cleanup(func() { affordanceLookup = orig })
-	affordanceLookup = func(_, _ string) (json.RawMessage, bool) {
-		return json.RawMessage(`{"use_when":["高层创建日程"]}`), true
-	}
-
-	const authored = "Custom docs help. AI agents MUST read the skill first."
-	sc := &cobra.Command{Use: "+create", Short: "Create", Long: authored}
-	cmdmeta.SetSource(sc, cmdmeta.SourceShortcut, false)
-	cmdmeta.SetAffordanceRef(sc, "calendar", "+create")
-
-	if !PrepareShortcutHelp(sc, nil) {
-		t.Fatal("PrepareShortcutHelp returned false for a shortcut with an overlay")
-	}
-	if !strings.HasPrefix(sc.Long, authored) {
-		t.Errorf("hand-authored Long must lead, not be clobbered; got:\n%s", sc.Long)
-	}
-	if !strings.Contains(sc.Long, "When to use:") {
-		t.Errorf("affordance block should be appended below the base; got:\n%s", sc.Long)
-	}
-	// Re-render must reuse the captured base, not append the block twice.
-	PrepareShortcutHelp(sc, nil)
-	if n := strings.Count(sc.Long, "When to use:"); n != 1 {
-		t.Errorf("affordance appended %d times across re-renders, want 1:\n%s", n, sc.Long)
-	}
-}
-
 // domainCmd wires a domain-tagged command with a subcommand under a root, the
 // shape PrepareDomainHelp expects.
 func domainCmd(short, long string) *cobra.Command {

cmd/service/service_test.go

@@ -4,14 +4,10 @@
 package service
 
 import (
-	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
-	"mime"
-	"mime/multipart"
 	"os"
-	"path/filepath"
 	"strings"
 	"testing"
 
@@ -1136,63 +1132,6 @@ func TestDetectFileFields(t *testing.T) {
 	}
 }
 
-// parseMultipartFilenames drives one service-method --file upload through the
-// mock transport and returns a map of field name -> part filename parsed from
-// the captured multipart body. Mirrors cmd/api's helper of the same name
-// (inlined here rather than shared, since the two live in different packages)
-// to give BuildFormdata's shared local-file fix a second real entry-point
-// covering it.
-func parseMultipartFilenames(t *testing.T, stub *httpmock.Stub) map[string]string {
-	t.Helper()
-	ct := stub.CapturedHeaders.Get("Content-Type")
-	mediaType, params, err := mime.ParseMediaType(ct)
-	if err != nil {
-		t.Fatalf("parse Content-Type %q: %v", ct, err)
-	}
-	if !strings.HasPrefix(mediaType, "multipart/") {
-		t.Fatalf("Content-Type = %q, want multipart/*", mediaType)
-	}
-	filenames := map[string]string{}
-	mr := multipart.NewReader(bytes.NewReader(stub.CapturedBody), params["boundary"])
-	for {
-		part, err := mr.NextPart()
-		if err != nil {
-			break
-		}
-		if fn := part.FileName(); fn != "" {
-			filenames[part.FormName()] = fn
-		}
-	}
-	return filenames
-}
-
-func TestServiceMethod_FileUpload_PreservesFilename(t *testing.T) {
-	f, _, _, reg := cmdutil.TestFactory(t, testConfig)
-
-	dir := t.TempDir()
-	cmdutil.TestChdir(t, dir)
-	if err := os.WriteFile(filepath.Join(dir, "photo.jpg"), []byte("fake-image"), 0600); err != nil {
-		t.Fatalf("write test file: %v", err)
-	}
-
-	stub := &httpmock.Stub{
-		URL:  "/open-apis/im/v1/images",
-		Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{"image_key": "img_xxx"}},
-	}
-	reg.Register(stub)
-
-	cmd := NewCmdServiceMethod(f, imSpec(), imImageMethod(), "create", "images", nil)
-	cmd.SetArgs([]string{"--file", "photo.jpg", "--data", `{"image_type":"message"}`, "--as", "bot"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	filenames := parseMultipartFilenames(t, stub)
-	if got := filenames["image"]; got != "photo.jpg" {
-		t.Fatalf("part filename for field %q = %q, want %q", "image", got, "photo.jpg")
-	}
-}
-
 func TestServiceMethod_JsonFlag_Accepted(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
 

dev-plans/lark-slides/README.md

@@ -0,0 +1,10 @@
+# Lark Slides Development Plans
+
+本目录只保存开发阶段计划、评审记录和执行拆解，不属于 `lark-slides` skill 的运行时提示词或工具使用参考。
+
+约束：
+
+- 不要从 `skills/lark-slides/SKILL.md` 路由到本目录。
+- 不要把本目录内容作为 agent 调用 `slides` 工具时的稳定协议或操作规范。
+- 当计划中的结论沉淀为长期有效规则时，先拆成原子化、可验证的运行时说明，再放入 `skills/lark-slides/references/` 或其下的专题目录。
+- 当计划仅用于阶段性开发判断时，继续留在本目录，避免污染工具提示词边界。

go.mod

@@ -10,7 +10,7 @@ require (
 	github.com/gofrs/flock v0.8.1
 	github.com/google/uuid v1.6.0
 	github.com/itchyny/gojq v0.12.17
-	github.com/larksuite/oapi-sdk-go/v3 v3.7.2
+	github.com/larksuite/oapi-sdk-go/v3 v3.5.4
 	github.com/sergi/go-diff v1.4.0
 	github.com/skip2/go-qrcode v0.0.0-20200617195104-da1b6568686e
 	github.com/smartystreets/goconvey v1.8.1

go.sum

@@ -79,8 +79,8 @@ github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORN
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0 h1:45sCR5RtlFHMR4UwH9sdQ5TC8v0qDQCHnXt+kaKSTVE=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
-github.com/larksuite/oapi-sdk-go/v3 v3.7.2 h1:SCIcXHRmtpQbiaZgDTDi1NYNCzrusi7ePJBR9uKoduE=
-github.com/larksuite/oapi-sdk-go/v3 v3.7.2/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
+github.com/larksuite/oapi-sdk-go/v3 v3.5.4 h1:U2S9x9LrfH++ZqJ+YAiUlqzCWJmVXhFdS8Z7rIBH8H0=
+github.com/larksuite/oapi-sdk-go/v3 v3.5.4/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
 github.com/lucasb-eyer/go-colorful v1.2.0 h1:1nnpGOrhyZZuNyfu1QjKiUICQ74+3FNCN69Aj6K7nkY=
 github.com/lucasb-eyer/go-colorful v1.2.0/go.mod h1:R4dSotOR9KMtayYi1e77YzuveK+i7ruzyGqttikkLy0=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=

internal/affordance/affordance.go

@@ -83,9 +83,10 @@ func commandFormResolver(service string) func(string) string {
 		}
 	}
 	return func(h string) string {
-		if id, ok := byForm[strings.TrimSpace(h)]; ok {
+		h = strings.TrimSpace(h)
+		if id, ok := byForm[h]; ok {
 			return id
 		}
-		return headingToKey(h) // one home for the shortcut/method key convention
+		return strings.ReplaceAll(h, " ", ".")
 	}
 }

internal/affordance/affordance_test.go

@@ -7,8 +7,6 @@ import (
 	"encoding/json"
 	"testing"
 	"testing/fstest"
-
-	"github.com/larksuite/cli/internal/meta"
 )
 
 // fixtureMD is a minimal affordance source: two methods, each with a lead
@@ -86,38 +84,3 @@ func TestParseDomainMD_ParagraphNotDropped(t *testing.T) {
 		t.Errorf("custom-section paragraph not flowed through: %+v", a.Extensions)
 	}
 }
-
-// The ### Skills section merges with the domain `> skill:` default: domain
-// first, then per-command entries, de-duplicated. A command with no ### Skills
-// still inherits the domain default.
-func TestParseDomainMD_SkillsMerge(t *testing.T) {
-	md := "# d\n> skill: lark-d\n\n" +
-		"## foo\ndoes foo.\n\n### Skills\n- lark-workflow\n- lark-d\n\n" + // lark-d duplicates the domain default
-		"## bar\ndoes bar.\n"
-	got := parseDomainMD([]byte(md), nil)
-
-	if a := got["foo"]; len(a.Skills) != 2 || a.Skills[0] != "lark-d" || a.Skills[1] != "lark-workflow" {
-		t.Errorf("foo skills = %v, want [lark-d lark-workflow] (domain first, deduped)", a.Skills)
-	}
-	if a := got["bar"]; len(a.Skills) != 1 || a.Skills[0] != "lark-d" {
-		t.Errorf("bar skills = %v, want [lark-d] (domain default inherited)", a.Skills)
-	}
-}
-
-// A +-prefixed shortcut heading keys verbatim (no space->dot folding), so it
-// matches the shortcut command as mounted.
-func TestParseDomainMD_ShortcutHeadingVerbatim(t *testing.T) {
-	md := "# d\n\n## +create\ncreate via shortcut.\n"
-	got := parseDomainMD([]byte(md), nil)
-	if _, ok := got["+create"]; !ok {
-		t.Errorf("shortcut heading should key as %q; got keys %v", "+create", keysOf(got))
-	}
-}
-
-func keysOf(m map[string]meta.Affordance) []string {
-	out := make([]string, 0, len(m))
-	for k := range m {
-		out = append(out, k)
-	}
-	return out
-}

internal/affordance/mdparse.go

@@ -19,7 +19,6 @@ import (
 //	### Prerequisites   -> prerequisites   (a "…来自 [[x]]" link is a sequence edge)
 //	### Tips            -> tips
 //	### Examples        -> examples: **description** + a ```fenced``` command
-//	### Skills          -> skills: bullet skill names, added to the domain default
 //	### <other>         -> extensions[] (custom section, flows through verbatim)
 //	[[cmd]]             -> a command reference, rendered as `cmd`
 //
@@ -35,56 +34,16 @@ var standardSection = map[string]string{
 	"Prerequisites": "prerequisites",
 	"Tips":          "tips",
 	"Examples":      "examples",
-	"Skills":        "skills",
-}
-
-// mergeSkills returns the domain-default skill followed by a command's own skill
-// entries, de-duplicated in author order and empties dropped. Backticks (left by
-// the shared bullet parse) are stripped so each entry is a bare skill name.
-func mergeSkills(domain string, extra []string) []string {
-	var out []string
-	seen := map[string]bool{}
-	add := func(s string) {
-		s = strings.Trim(strings.TrimSpace(s), "`")
-		if s == "" || seen[s] {
-			return
-		}
-		seen[s] = true
-		out = append(out, s)
-	}
-	add(domain)
-	for _, s := range extra {
-		add(s)
-	}
-	return out
 }
 
 func linkToBacktick(s string) string { return mdLink.ReplaceAllString(s, "`$1`") }
 
-// SkillStatPath maps a `### Skills` entry to the path (relative to the skill
-// tree) whose existence gates it: a bare skill name resolves to its SKILL.md,
-// while an entry containing a slash is a name/relative-path reference (e.g.
-// "lark-contact/references/lark-contact-search-user.md") and resolves to that
-// path directly. Both render as `lark-cli skills read <entry>` — the slash form
-// skills read already accepts — so a per-command entry can point at that
-// command's own reference file, not just re-point the domain skill.
-func SkillStatPath(entry string) string {
-	if strings.Contains(entry, "/") {
-		return entry
-	}
-	return entry + "/SKILL.md"
-}
-
 // headingToKey maps a command heading ("instances get") to its affordance key
 // ("instances.get"). The space→dot rule holds where the command form matches
 // the method id; domains whose resource names differ (e.g. plural "messages"
 // vs id segment "message") need the registry's authoritative resource↔id table.
 func headingToKey(h string) string {
-	h = strings.TrimSpace(h)
-	if strings.HasPrefix(h, "+") { // shortcut command: key is the command verbatim
-		return h
-	}
-	return strings.ReplaceAll(h, " ", ".")
+	return strings.ReplaceAll(strings.TrimSpace(h), " ", ".")
 }
 
 type mdSection struct {
@@ -123,7 +82,6 @@ func parseDomainMD(src []byte, resolve func(string) string) map[string]meta.Affo
 		if len(useWhen) > 0 {
 			a.UseWhen = useWhen
 		}
-		var perCmdSkills []string
 		for _, s := range secs {
 			switch standardSection[s.label] {
 			case "avoid_when":
@@ -134,14 +92,12 @@ func parseDomainMD(src []byte, resolve func(string) string) map[string]meta.Affo
 				a.Tips = s.items
 			case "examples":
 				a.Examples = s.cases
-			case "skills":
-				perCmdSkills = s.items
 			default:
 				a.Extensions = append(a.Extensions, meta.AffordanceSection{Label: s.label, Items: s.items})
 			}
 		}
-		if s := mergeSkills(skill, perCmdSkills); len(s) > 0 {
-			a.Skills = s
+		if skill != "" {
+			a.Skills = []string{skill}
 		}
 		out[curKey] = a
 	}
@@ -201,7 +157,7 @@ func parseDomainMD(src []byte, resolve func(string) string) map[string]meta.Affo
 				inFence, fence = true, nil
 			} else {
 				inFence = false
-				sec.cases = append(sec.cases, meta.AffordanceCase{Description: linkToBacktick(pending), Command: strings.Join(fence, "\n")})
+				sec.cases = append(sec.cases, meta.AffordanceCase{Description: pending, Command: strings.Join(fence, "\n")})
 				pending = ""
 			}
 			continue

internal/cmdmeta/meta.go

@@ -2,11 +2,9 @@
 // SPDX-License-Identifier: MIT
 
 // Package cmdmeta is the single source of truth for command metadata that the
-// policy engine, the hook selector, and help rendering consume. It wraps the
-// existing cmdutil annotations (risk_level, supportedIdentities) and adds the
-// "domain" axis that the hook selector and Rule path globs need, plus the
-// affordance ref (service, method id) that lets service-method and shortcut
-// help share one usage-guidance lookup path.
+// policy engine and the hook selector both consume. It wraps the existing
+// cmdutil annotations (risk_level, supportedIdentities) and adds the
+// "domain" axis that the hook selector and Rule path globs need.
 //
 // Three axes:
 //
@@ -53,12 +51,6 @@ const (
 
 	sourceAnnotationKey    = "cmdmeta.source"
 	generatedAnnotationKey = "cmdmeta.generated"
-
-	// affordance{Service,Method}Key locate the command's usage-guidance overlay
-	// entry (see internal/affordance). Both service-method commands and
-	// +-prefixed shortcuts set these so help rendering shares one lookup path.
-	affordanceServiceKey = "cmdmeta.affordance.service"
-	affordanceMethodKey  = "cmdmeta.affordance.method"
 )
 
 // Meta groups the three command-level metadata axes consumed by the policy
@@ -133,35 +125,6 @@ func SetSource(cmd *cobra.Command, source Source, generated bool) {
 	}
 }
 
-// SetAffordanceRef records which affordance overlay entry (service, method id)
-// a command maps to, so help rendering can look up its usage guidance. Stored
-// on the command itself (no inheritance): each method / shortcut owns its ref.
-// A no-op if either coordinate is empty.
-func SetAffordanceRef(cmd *cobra.Command, service, method string) {
-	if service == "" || method == "" {
-		return
-	}
-	if cmd.Annotations == nil {
-		cmd.Annotations = map[string]string{}
-	}
-	cmd.Annotations[affordanceServiceKey] = service
-	cmd.Annotations[affordanceMethodKey] = method
-}
-
-// AffordanceRef returns the command's own affordance overlay coordinates.
-// ok is false when the command carries no ref.
-func AffordanceRef(cmd *cobra.Command) (service, method string, ok bool) {
-	if cmd.Annotations == nil {
-		return "", "", false
-	}
-	service = cmd.Annotations[affordanceServiceKey]
-	method = cmd.Annotations[affordanceMethodKey]
-	if service == "" || method == "" {
-		return "", "", false
-	}
-	return service, method, true
-}
-
 // Domain returns the nearest-ancestor domain for the command. Empty string
 // when no ancestor has the annotation -- this is the "unknown" state the
 // policy engine must treat as ALLOW.

internal/cmdutil/fileupload.go

@@ -7,7 +7,6 @@ import (
 	"bytes"
 	"fmt"
 	"io"
-	"path/filepath"
 	"strconv"
 	"strings"
 
@@ -129,7 +128,7 @@ func BuildFormdata(fileIO fileio.FileIO, fieldName, filePath string, isStdin boo
 				WithParam("--file").
 				WithCause(err)
 		}
-		fd.AddFileWithName(fieldName, filepath.Base(filePath), bytes.NewReader(data))
+		fd.AddFile(fieldName, bytes.NewReader(data))
 	}
 
 	// Add top-level JSON keys as text form fields.

internal/meta/affordance.go

@@ -8,11 +8,8 @@ import "encoding/json"
 // Affordance is the typed usage guidance overlaid on a method. It is the single
 // model the envelope renderer and the command help both parse, so the
 // vocabulary is defined once; the JSON tags double as the envelope wire shape.
-// Skills entries are either a bare skill name (e.g. "lark-doc") or a
-// name/relative-path reference (e.g. "lark-contact/references/x.md"); both
-// render as runnable `lark-cli skills read <entry>` pointers. Help validates
-// each against the embedded skill tree (a name → its SKILL.md, a reference →
-// that path) and drops any that do not resolve.
+// Skills entries are skill names (or name/path) rendered as runnable
+// `lark-cli skills read <entry>` pointers.
 type Affordance struct {
 	UseWhen       []string            `json:"use_when,omitempty"`
 	AvoidWhen     []string            `json:"avoid_when,omitempty"`

package.json

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

shortcuts/apps/apps_db_audit_list.go

@@ -40,7 +40,7 @@ var AppsDBAuditList = common.Shortcut{
 		{Name: "until", Desc: "filter: event at or before; same formats as --since"},
 		{Name: "page-size", Type: "int", Default: "20", Desc: "page size"},
 		{Name: "page-token", Desc: "pagination cursor from previous response"},
-	}, dbEnvFlags("", []string{"dev", "online"}, "target db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	}, dbEnvFlags("dev", []string{"dev", "online"}, "target db environment (default dev; use online for the online environment, or for an app whose DB is not multi-env)")...),
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
@@ -145,10 +145,7 @@ func fetchExistingTables(rctx *common.RuntimeContext, appID, env string) (map[st
 	existing := map[string]bool{}
 	token := ""
 	for {
-		params := map[string]interface{}{"page_size": 100}
-		if env != "" {
-			params["env"] = env
-		}
+		params := map[string]interface{}{"env": env, "page_size": 100}
 		if token != "" {
 			params["page_token"] = token
 		}
@@ -171,11 +168,7 @@ func fetchExistingTables(rctx *common.RuntimeContext, appID, env string) (map[st
 
 // fetchAuditEnabledTables 拉审计状态，返回当前已开启审计的表名集合（status 命令同源接口）。
 func fetchAuditEnabledTables(rctx *common.RuntimeContext, appID, env string) (map[string]bool, error) {
-	statusParams := map[string]interface{}{}
-	if env != "" {
-		statusParams["env"] = env
-	}
-	data, err := rctx.CallAPITyped("GET", appAuditStatusPath(appID), statusParams, nil)
+	data, err := rctx.CallAPITyped("GET", appAuditStatusPath(appID), map[string]interface{}{"env": env}, nil)
 	if err != nil {
 		return nil, err
 	}
@@ -215,10 +208,11 @@ func auditListTables(rctx *common.RuntimeContext) []string {
 
 // buildAuditListParams 组装 audit_list 查询参数：env / tables(逗号拼接) / page_size 及可选 since/until/page_token。
 func buildAuditListParams(rctx *common.RuntimeContext, tables []string) map[string]interface{} {
-	params := dbEnvParams(rctx, map[string]interface{}{
+	params := map[string]interface{}{
+		"env":       dbEnv(rctx),
 		"tables":    strings.Join(tables, ","),
 		"page_size": rctx.Int("page-size"),
-	})
+	}
 	addStr := func(flag, key string) {
 		if v := strings.TrimSpace(rctx.Str(flag)); v != "" {
 			params[key] = v

shortcuts/apps/apps_db_audit_set.go

@@ -35,7 +35,7 @@ var AppsDBAuditEnable = common.Shortcut{
 		{Name: "app-id", Desc: "Miaoda app id", Required: true},
 		{Name: "table", Desc: "table to enable audit for", Required: true},
 		{Name: "retention", Default: "7d", Enum: auditRetentions, Desc: "how long to keep audit logs"},
-	}, dbEnvFlags("", []string{"dev", "online"}, "target db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	}, dbEnvFlags("dev", []string{"dev", "online"}, "target db environment (default dev; use online for the online environment, or for an app whose DB is not multi-env)")...),
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
@@ -47,7 +47,7 @@ var AppsDBAuditEnable = common.Shortcut{
 		return common.NewDryRunAPI().
 			POST(appAuditSetPath(appID)).
 			Desc("Enable table audit").
-			Params(dbEnvParams(rctx, map[string]interface{}{})).
+			Params(map[string]interface{}{"env": dbEnv(rctx)}).
 			Body(map[string]interface{}{"table": strings.TrimSpace(rctx.Str("table")), "enabled": true, "retention": rctx.Str("retention")})
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
@@ -60,7 +60,7 @@ var AppsDBAuditEnable = common.Shortcut{
 		stop := rctx.StartSpinner("Enabling audit logging for " + table)
 		defer stop()
 		data, err := rctx.CallAPITyped("POST", appAuditSetPath(appID),
-			dbEnvParams(rctx, map[string]interface{}{}),
+			map[string]interface{}{"env": dbEnv(rctx)},
 			map[string]interface{}{"table": table, "enabled": true, "retention": retention})
 		stop()
 		if err != nil {
@@ -96,7 +96,7 @@ var AppsDBAuditDisable = common.Shortcut{
 	Flags: append([]common.Flag{
 		{Name: "app-id", Desc: "Miaoda app id", Required: true},
 		{Name: "table", Desc: "table to disable audit for", Required: true},
-	}, dbEnvFlags("", []string{"dev", "online"}, "target db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	}, dbEnvFlags("dev", []string{"dev", "online"}, "target db environment (default dev; use online for the online environment, or for an app whose DB is not multi-env)")...),
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
@@ -108,7 +108,7 @@ var AppsDBAuditDisable = common.Shortcut{
 		return common.NewDryRunAPI().
 			POST(appAuditSetPath(appID)).
 			Desc("Disable table audit").
-			Params(dbEnvParams(rctx, map[string]interface{}{})).
+			Params(map[string]interface{}{"env": dbEnv(rctx)}).
 			Body(map[string]interface{}{"table": strings.TrimSpace(rctx.Str("table")), "enabled": false})
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
@@ -118,7 +118,7 @@ var AppsDBAuditDisable = common.Shortcut{
 		}
 		table := strings.TrimSpace(rctx.Str("table"))
 		data, err := rctx.CallAPITyped("POST", appAuditSetPath(appID),
-			dbEnvParams(rctx, map[string]interface{}{}),
+			map[string]interface{}{"env": dbEnv(rctx)},
 			map[string]interface{}{"table": table, "enabled": false})
 		if err != nil {
 			return withAppsHint(err, dbAuditSetHint)

shortcuts/apps/apps_db_audit_status.go

@@ -30,7 +30,7 @@ var AppsDBAuditStatus = common.Shortcut{
 	Flags: append([]common.Flag{
 		{Name: "app-id", Desc: "Miaoda app id", Required: true},
 		{Name: "table", Desc: "show status for a single table (default: all configured tables)"},
-	}, dbEnvFlags("", []string{"dev", "online"}, "target db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	}, dbEnvFlags("dev", []string{"dev", "online"}, "target db environment (default dev; use online for the online environment, or for an app whose DB is not multi-env)")...),
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
@@ -75,7 +75,7 @@ var AppsDBAuditStatus = common.Shortcut{
 
 // buildAuditStatusParams 组装 audit_status 查询参数：env 及可选 table（单表查询）。
 func buildAuditStatusParams(rctx *common.RuntimeContext) map[string]interface{} {
-	params := dbEnvParams(rctx, map[string]interface{}{})
+	params := map[string]interface{}{"env": dbEnv(rctx)}
 	if t := strings.TrimSpace(rctx.Str("table")); t != "" {
 		params["table"] = t
 	}

shortcuts/apps/apps_db_changelog_list.go

@@ -39,7 +39,7 @@ var AppsDBChangelogList = common.Shortcut{
 		{Name: "until", Desc: "filter: changed at or before; same formats as --since"},
 		{Name: "page-size", Type: "int", Default: "20", Desc: "page size"},
 		{Name: "page-token", Desc: "pagination cursor from previous response"},
-	}, dbEnvFlags("", []string{"dev", "online"}, "target db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	}, dbEnvFlags("dev", []string{"dev", "online"}, "target db environment (default dev; use online for the online environment, or for an app whose DB is not multi-env)")...),
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
@@ -77,9 +77,10 @@ var AppsDBChangelogList = common.Shortcut{
 
 // buildChangelogParams 组装 changelog_list 查询参数：env / page_size 及可选 table/change_id/since/until/page_token。
 func buildChangelogParams(rctx *common.RuntimeContext) map[string]interface{} {
-	params := dbEnvParams(rctx, map[string]interface{}{
+	params := map[string]interface{}{
+		"env":       dbEnv(rctx),
 		"page_size": rctx.Int("page-size"),
-	})
+	}
 	addStr := func(flag, key string) {
 		if v := strings.TrimSpace(rctx.Str(flag)); v != "" {
 			params[key] = v

shortcuts/apps/apps_db_data_export.go

@@ -47,7 +47,7 @@ var AppsDBDataExport = common.Shortcut{
 		{Name: "table", Desc: "source table", Required: true},
 		{Name: "output", Desc: "local output path; extension picks format .csv/.json/.sql (default: <table>.csv)"},
 		{Name: "limit", Type: "int", Default: "5000", Desc: "max rows to export (1..5000)"},
-	}, dbEnvFlags("", []string{"dev", "online"}, "source db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	}, dbEnvFlags("dev", []string{"dev", "online"}, "source db environment (default dev; use online for the online environment, or for an app whose DB is not multi-env)")...),
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
@@ -75,10 +75,10 @@ var AppsDBDataExport = common.Shortcut{
 		return common.NewDryRunAPI().
 			GET(appDataExportPath(appID)).
 			Desc("Export Miaoda app table data (raw bytes)").
-			Params(dbEnvParams(rctx, map[string]interface{}{
-				"table":  strings.TrimSpace(rctx.Str("table")),
+			Params(map[string]interface{}{
+				"env": dbEnv(rctx), "table": strings.TrimSpace(rctx.Str("table")),
 				"format": format, "limit": rctx.Int("limit"),
-			}))
+			})
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		appID, err := requireAppID(rctx.Str("app-id"))
@@ -95,18 +95,15 @@ var AppsDBDataExport = common.Shortcut{
 		// total 查询失败不阻断导出——回退到按导出文件内容数行。
 		total, totalErr := queryExportTotal(rctx, appID, dbEnv(rctx), table)
 
-		exportQuery := larkcore.QueryParams{
-			"table":  []string{table},
-			"format": []string{format},
-			"limit":  []string{strconv.Itoa(rctx.Int("limit"))},
-		}
-		if env := dbEnv(rctx); env != "" {
-			exportQuery["env"] = []string{env}
-		}
 		resp, err := rctx.DoAPI(&larkcore.ApiReq{
-			HttpMethod:  http.MethodGet,
-			ApiPath:     appDataExportPath(appID),
-			QueryParams: exportQuery,
+			HttpMethod: http.MethodGet,
+			ApiPath:    appDataExportPath(appID),
+			QueryParams: larkcore.QueryParams{
+				"env":    []string{dbEnv(rctx)},
+				"table":  []string{table},
+				"format": []string{format},
+				"limit":  []string{strconv.Itoa(rctx.Int("limit"))},
+			},
 		})
 		if err != nil {
 			return withAppsHint(errs.NewNetworkError(errs.SubtypeNetworkTransport, "export request failed").WithCause(err).WithRetryable(), dbDataExportHint)
@@ -160,11 +157,8 @@ var AppsDBDataExport = common.Shortcut{
 // queryExportTotal 调 GetAppTableRecordList（page_size=1）取 total（符合条件的记录总数）。
 // 该接口与 +db-data-export 同为 spark:app:read scope，避免导出命令被迫升级到写权限。
 func queryExportTotal(rctx *common.RuntimeContext, appID, env, table string) (int, error) {
-	params := map[string]interface{}{"page_size": 1}
-	if env != "" {
-		params["env"] = env
-	}
-	raw, err := rctx.CallAPITyped("GET", appTableRecordsPath(appID, table), params, nil)
+	raw, err := rctx.CallAPITyped("GET", appTableRecordsPath(appID, table),
+		map[string]interface{}{"env": env, "page_size": 1}, nil)
 	if err != nil {
 		return 0, err
 	}

shortcuts/apps/apps_db_data_import.go

@@ -44,7 +44,7 @@ var AppsDBDataImport = common.Shortcut{
 		{Name: "app-id", Desc: "Miaoda app id", Required: true},
 		{Name: "file", Desc: "local data file (.csv/.json), relative to cwd", Required: true},
 		{Name: "table", Desc: "target table (default: file name without extension)"},
-	}, dbEnvFlags("", []string{"dev", "online"}, "target db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	}, dbEnvFlags("dev", []string{"dev", "online"}, "target db environment (default dev; use online for the online environment, or for an app whose DB is not multi-env)")...),
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
@@ -76,7 +76,7 @@ var AppsDBDataImport = common.Shortcut{
 		return common.NewDryRunAPI().
 			POST(appDataImportPath(appID)).
 			Desc("Import data file into Miaoda app table (multipart upload)").
-			Params(dbEnvParams(rctx, map[string]interface{}{"table": importTableName(rctx)})).
+			Params(map[string]interface{}{"env": dbEnv(rctx), "table": importTableName(rctx)}).
 			Body(map[string]interface{}{"file_name": fileName, "file": "<contents of --file>"})
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
@@ -100,14 +100,10 @@ var AppsDBDataImport = common.Shortcut{
 		fd.AddField("file_name", fileName)
 		fd.AddFile("file", bytes.NewReader(content))
 
-		importQuery := larkcore.QueryParams{"table": []string{table}}
-		if env := dbEnv(rctx); env != "" {
-			importQuery["env"] = []string{env}
-		}
 		resp, err := rctx.DoAPI(&larkcore.ApiReq{
 			HttpMethod:  http.MethodPost,
 			ApiPath:     appDataImportPath(appID),
-			QueryParams: importQuery,
+			QueryParams: larkcore.QueryParams{"env": []string{dbEnv(rctx)}, "table": []string{table}},
 			Body:        fd,
 		}, larkcore.WithFileUpload())
 		if err != nil {

shortcuts/apps/apps_db_data_import_test.go

@@ -121,31 +121,6 @@ func TestAppsDBDataImport_DryRunMultipartShape(t *testing.T) {
 	}
 }
 
-// TestAppsDBDataImport_DryRunOmitsEnvWhenUnset 验证不传 --environment 时 dry-run 的 query
-// 不带 env 键（交服务端按应用形态自动选分支），但仍携带 table。
-func TestAppsDBDataImport_DryRunOmitsEnvWhenUnset(t *testing.T) {
-	chdirTemp(t)
-	_ = os.WriteFile("orders.csv", []byte("id\n1\n"), 0o600)
-	factory, stdout, _ := newAppsExecuteFactory(t)
-	if err := runAppsShortcut(t, AppsDBDataImport,
-		[]string{"+db-data-import", "--app-id", "app_x", "--file", "orders.csv", "--dry-run", "--yes", "--as", "user"}, factory, stdout); err != nil {
-		t.Fatalf("dry-run err=%v", err)
-	}
-	var env struct {
-		API []struct {
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
-	_ = json.Unmarshal([]byte(stdout.String()), &env)
-	p := env.API[0].Params
-	if _, ok := p["env"]; ok {
-		t.Fatalf("no --environment → env key must be omitted, got params=%v", p)
-	}
-	if p["table"] != "orders" {
-		t.Fatalf("table should still default to file basename, got params=%v", p)
-	}
-}
-
 // TestAppsDBDataImport_Success 验证成功导入后输出含 table、rows 与回显的 file 名。
 func TestAppsDBDataImport_Success(t *testing.T) {
 	chdirTemp(t)

shortcuts/apps/apps_db_env_migrate.go

@@ -97,16 +97,6 @@ var AppsDBEnvMigrate = common.Shortcut{
 		if err != nil {
 			return err
 		}
-		// 先 dry_run 预览拿待发布变更数（对齐 miaoda-cli 的 diff-then-apply）：服务端在未经
-		// dry_run 预热时直接 apply，虽发布成功却把 changes_applied 回填成 0（展示「Migrated (0 changes)」）。
-		// 这一步既预热服务端计数、又作为 apply 仍回 0 时的兜底数。dry_run 报错（如无待发布变更）不阻断，
-		// 交由下面真实 apply 统一报同样的业务错。
-		pending := 0
-		var previewFrom, previewTo string
-		if preview, perr := rctx.CallAPITyped("POST", appEnvMigratePath(appID), nil, map[string]interface{}{"dry_run": true}); perr == nil {
-			pending = len(projectMigrationChanges(preview["changes"]))
-			previewFrom, previewTo = common.GetString(preview, "from"), common.GetString(preview, "to")
-		}
 		stop := rctx.StartSpinner("Applying migration (dev → online)")
 		defer stop()
 		submit, err := rctx.CallAPITyped("POST", appEnvMigratePath(appID), nil, map[string]interface{}{"dry_run": false})
@@ -114,12 +104,6 @@ var AppsDBEnvMigrate = common.Shortcut{
 			return withAppsHint(err, dbEnvMigrateHint)
 		}
 		from, to := common.GetString(submit, "from"), common.GetString(submit, "to")
-		if from == "" {
-			from = previewFrom
-		}
-		if to == "" {
-			to = previewTo
-		}
 		taskID := common.GetString(submit, "task_id")
 		applied := intFromAny(submit["changes_applied"])
 		if applied == 0 {
@@ -147,10 +131,6 @@ var AppsDBEnvMigrate = common.Shortcut{
 				applied = n
 			}
 		}
-		// 服务端把发布成功的变更数回 0 时，用发布前 dry_run 预览的 pending 数兜底，避免误显示「(0 changes)」。
-		if applied == 0 && pending > 0 {
-			applied = pending
-		}
 		stop() // clear spinner before printing the result
 		out := map[string]interface{}{"status": "migrated", "from": from, "to": to, "changes_applied": applied}
 		rctx.OutFormat(out, nil, func(w io.Writer) {

shortcuts/apps/apps_db_env_recovery_quota_test.go

@@ -105,10 +105,8 @@ func TestAppsDBEnvMigrate_DryRunBody(t *testing.T) {
 // 异步：submit 返 task_id，status 立刻 applied → CLI 对外统一 migrated。
 func TestAppsDBEnvMigrate_AsyncPollSuccess(t *testing.T) {
 	factory, stdout, reg := newAppsExecuteFactory(t)
-	// Reusable：Execute 现在会先打一次 dry_run 预览拿待发布数、再打 apply（对齐 miaoda-cli 的
-	// diff-then-apply，兜底服务端 apply 少报 changes_applied 的情况），故同一 POST 端点被调用两次。
 	reg.Register(&httpmock.Stub{
-		Method: "POST", URL: dbEnvMigrateURL, Reusable: true,
+		Method: "POST", URL: dbEnvMigrateURL,
 		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"from": "dev", "to": "online", "task_id": "t1"}},
 	})
 	reg.Register(&httpmock.Stub{
@@ -128,10 +126,8 @@ func TestAppsDBEnvMigrate_AsyncPollSuccess(t *testing.T) {
 // TestAppsDBEnvMigrate_PollFailedSurfacesError 验证轮询到 failed 时返回 API/server_error 类型错误，携带服务端 message 与恢复 hint。
 func TestAppsDBEnvMigrate_PollFailedSurfacesError(t *testing.T) {
 	factory, stdout, reg := newAppsExecuteFactory(t)
-	// Reusable：Execute 现在会先打一次 dry_run 预览拿待发布数、再打 apply（对齐 miaoda-cli 的
-	// diff-then-apply，兜底服务端 apply 少报 changes_applied 的情况），故同一 POST 端点被调用两次。
 	reg.Register(&httpmock.Stub{
-		Method: "POST", URL: dbEnvMigrateURL, Reusable: true,
+		Method: "POST", URL: dbEnvMigrateURL,
 		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"from": "dev", "to": "online", "task_id": "t1"}},
 	})
 	reg.Register(&httpmock.Stub{
@@ -323,31 +319,6 @@ func TestAppsDBQuotaGet_WithQuotaPretty(t *testing.T) {
 }
 
 // 配额未对接（storage_quota_bytes=0）→ json 删 quota/usage_percent，仅留已用量与 tables/views。
-// TestAppsDBQuotaGet_DryRunOmitsEnvWhenUnset 验证不传 --environment 时 quota-get 的 dry-run
-// query 不带 env 键（交服务端按应用形态自动选分支）。
-func TestAppsDBQuotaGet_DryRunOmitsEnvWhenUnset(t *testing.T) {
-	factory, stdout, _ := newAppsExecuteFactory(t)
-	if err := runAppsShortcut(t, AppsDBQuotaGet,
-		[]string{"+db-quota-get", "--app-id", "app_x", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
-		t.Fatalf("dry-run err=%v", err)
-	}
-	var env struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Params map[string]interface{} `json:"params"`
-		} `json:"api"`
-	}
-	_ = json.Unmarshal([]byte(stdout.String()), &env)
-	a := env.API[0]
-	if a.Method != "GET" || a.URL != dbQuotaURL {
-		t.Fatalf("dry-run = %s %s", a.Method, a.URL)
-	}
-	if _, ok := a.Params["env"]; ok {
-		t.Fatalf("no --environment → env key must be omitted, got params=%v", a.Params)
-	}
-}
-
 func TestAppsDBQuotaGet_NoQuotaOmitsFields(t *testing.T) {
 	factory, stdout, reg := newAppsExecuteFactory(t)
 	reg.Register(&httpmock.Stub{

shortcuts/apps/apps_db_execute.go

@@ -66,7 +66,7 @@ var AppsDBExecute = common.Shortcut{
 		{Name: "sql", Desc: "SQL text; use - to read stdin. Mutually exclusive with --file",
 			Input: []string{common.Stdin}},
 		{Name: "file", Desc: "path to a .sql file (relative to cwd). Mutually exclusive with --sql"},
-	}, dbEnvFlags("", []string{"dev", "online"}, "target db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	}, dbEnvFlags("dev", []string{"dev", "online"}, "target db environment (default dev; use online for the online environment, or for an app whose DB is not multi-env)")...),
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
@@ -291,9 +291,10 @@ func parseErrorSentinel(data string) (int, string) {
 //
 // CLI 永远走 DBA 模式，原子性由用户在 SQL 内显式 BEGIN/COMMIT 控制；不暴露 transactional flag 给用户。
 func buildDBSQLParams(rctx *common.RuntimeContext) map[string]interface{} {
-	return dbEnvParams(rctx, map[string]interface{}{
+	return map[string]interface{}{
+		"env":           dbEnv(rctx),
 		"transactional": false,
-	})
+	}
 }
 
 // resolveExecuteSQL 返回要执行的 SQL，在用时（DryRun/Execute）现读，使 --file 的内容

shortcuts/apps/apps_db_quota_get.go

@@ -29,7 +29,7 @@ var AppsDBQuotaGet = common.Shortcut{
 	HasFormat: true,
 	Flags: append([]common.Flag{
 		{Name: "app-id", Desc: "Miaoda app id", Required: true},
-	}, dbEnvFlags("", []string{"dev", "online"}, "target db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	}, dbEnvFlags("dev", []string{"dev", "online"}, "target db environment (default dev; use online for the online environment, or for an app whose DB is not multi-env)")...),
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
@@ -41,14 +41,14 @@ var AppsDBQuotaGet = common.Shortcut{
 		return common.NewDryRunAPI().
 			GET(appDbQuotaPath(appID)).
 			Desc("Get Miaoda app database storage usage").
-			Params(dbEnvParams(rctx, map[string]interface{}{}))
+			Params(map[string]interface{}{"env": dbEnv(rctx)})
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		appID, err := requireAppID(rctx.Str("app-id"))
 		if err != nil {
 			return err
 		}
-		data, err := rctx.CallAPITyped("GET", appDbQuotaPath(appID), dbEnvParams(rctx, map[string]interface{}{}), nil)
+		data, err := rctx.CallAPITyped("GET", appDbQuotaPath(appID), map[string]interface{}{"env": dbEnv(rctx)}, nil)
 		if err != nil {
 			return withAppsHint(err, appIDListHint)
 		}

shortcuts/apps/apps_db_recovery.go

@@ -32,23 +32,19 @@ var AppsDBRecoveryDiff = common.Shortcut{
 	Scopes:    []string{"spark:app:write"},
 	AuthTypes: []string{"user"},
 	HasFormat: true,
-	Flags: append([]common.Flag{
+	Flags: []common.Flag{
 		{Name: "app-id", Desc: "Miaoda app id", Required: true},
 		{Name: "target", Desc: "point in time to restore to; relative (2h/3d) | date | datetime | ISO 8601 w/ TZ", Required: true},
-	}, dbEnvFlags("", []string{"dev", "online"}, "target db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
 		}
-		if err := rejectLegacyEnvFlag(rctx); err != nil {
-			return err
-		}
 		return normalizeTimeFlags(rctx, "target")
 	},
 	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
 		appID, _ := requireAppID(rctx.Str("app-id"))
 		return common.NewDryRunAPI().POST(appRecoveryPath(appID)).Desc("Preview PITR recovery").
-			Params(dbEnvParams(rctx, map[string]interface{}{})).
 			Body(map[string]interface{}{"target": rctx.Str("target"), "dry_run": true})
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
@@ -85,23 +81,19 @@ var AppsDBRecoveryApply = common.Shortcut{
 	Scopes:    []string{"spark:app:write"},
 	AuthTypes: []string{"user"},
 	HasFormat: true,
-	Flags: append([]common.Flag{
+	Flags: []common.Flag{
 		{Name: "app-id", Desc: "Miaoda app id", Required: true},
 		{Name: "target", Desc: "point in time to restore to; relative (2h/3d) | date | datetime | ISO 8601 w/ TZ", Required: true},
-	}, dbEnvFlags("", []string{"dev", "online"}, "target db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	},
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
 		}
-		if err := rejectLegacyEnvFlag(rctx); err != nil {
-			return err
-		}
 		return normalizeTimeFlags(rctx, "target")
 	},
 	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
 		appID, _ := requireAppID(rctx.Str("app-id"))
 		return common.NewDryRunAPI().POST(appRecoveryPath(appID)).Desc("Apply PITR recovery").
-			Params(dbEnvParams(rctx, map[string]interface{}{})).
 			Body(map[string]interface{}{"target": rctx.Str("target"), "dry_run": false})
 	},
 	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
@@ -112,7 +104,7 @@ var AppsDBRecoveryApply = common.Shortcut{
 		target := rctx.Str("target")
 		stop := rctx.StartSpinner("Restoring database (target: " + target + ")")
 		defer stop()
-		submit, err := rctx.CallAPITyped("POST", appRecoveryPath(appID), dbEnvParams(rctx, map[string]interface{}{}), map[string]interface{}{"target": target, "dry_run": false})
+		submit, err := rctx.CallAPITyped("POST", appRecoveryPath(appID), nil, map[string]interface{}{"target": target, "dry_run": false})
 		if err != nil {
 			return withAppsHint(err, dbRecoveryHint)
 		}
@@ -127,7 +119,7 @@ var AppsDBRecoveryApply = common.Shortcut{
 		}
 		final, perr := pollUntil(rctx.Ctx(), 2*time.Second, 2*time.Minute,
 			func() (map[string]interface{}, error) {
-				return rctx.CallAPITyped("GET", appRecoveryApplyStatusPath(appID), dbEnvParams(rctx, map[string]interface{}{}), nil)
+				return rctx.CallAPITyped("GET", appRecoveryApplyStatusPath(appID), nil, nil)
 			},
 			func(d map[string]interface{}) (bool, error) {
 				switch strings.ToLower(common.GetString(d, "status")) {
@@ -165,7 +157,7 @@ var AppsDBRecoveryApply = common.Shortcut{
 func runRecoveryPreview(rctx *common.RuntimeContext, appID, target string) (map[string]interface{}, error) {
 	stop := rctx.StartSpinner("Previewing recovery impact (target: " + target + ")")
 	defer stop()
-	submit, err := rctx.CallAPITyped("POST", appRecoveryPath(appID), dbEnvParams(rctx, map[string]interface{}{}), map[string]interface{}{"target": target, "dry_run": true})
+	submit, err := rctx.CallAPITyped("POST", appRecoveryPath(appID), nil, map[string]interface{}{"target": target, "dry_run": true})
 	if err != nil {
 		return nil, withAppsHint(err, dbRecoveryHint)
 	}
@@ -175,7 +167,7 @@ func runRecoveryPreview(rctx *common.RuntimeContext, appID, target string) (map[
 	}
 	return pollUntil(rctx.Ctx(), 1*time.Second, 2*time.Minute,
 		func() (map[string]interface{}, error) {
-			return rctx.CallAPITyped("GET", appRecoveryDiffStatusPath(appID), dbEnvParams(rctx, map[string]interface{}{"preview_request_id": prid}), nil)
+			return rctx.CallAPITyped("GET", appRecoveryDiffStatusPath(appID), map[string]interface{}{"preview_request_id": prid}, nil)
 		},
 		func(d map[string]interface{}) (bool, error) {
 			switch strings.ToLower(common.GetString(d, "preview_status")) {
@@ -203,13 +195,13 @@ type recoveryChange struct {
 // recoveryDiffOutput 组装 diff 输出：target / tables_affected / changes[] / estimated_seconds。
 func recoveryDiffOutput(target string, preview map[string]interface{}) map[string]interface{} {
 	arr, _ := preview["changes"].([]interface{})
-	raw := make([]recoveryChange, 0, len(arr))
+	changes := make([]recoveryChange, 0, len(arr))
 	for _, it := range arr {
 		m, ok := it.(map[string]interface{})
 		if !ok {
 			continue
 		}
-		raw = append(raw, recoveryChange{
+		changes = append(changes, recoveryChange{
 			Table:     common.GetString(m, "table"),
 			Inserted:  m["inserted"],
 			Deleted:   m["deleted"],
@@ -217,33 +209,16 @@ func recoveryDiffOutput(target string, preview map[string]interface{}) map[strin
 			DroppedAt: common.GetString(m, "dropped_at"),
 		})
 	}
-	// 服务端可能对同一张表既下发 schema 动作(drop/restore/alter)、又下发纯数据行变更。
-	// schema 动作已涵盖数据结果(如 drop 隐含删光行)，丢弃该表的冗余数据行那条，避免同表
-	// 两行 + tables_affected 翻倍。
-	hasSchema := map[string]bool{}
-	for _, c := range raw {
-		if c.Action != "" {
-			hasSchema[c.Table] = true
-		}
-	}
-	changes := make([]recoveryChange, 0, len(raw))
-	for _, c := range raw {
-		if c.Action == "" && hasSchema[c.Table] {
-			continue
-		}
-		changes = append(changes, c)
-	}
-	// tables_affected 按去重后的不同表数计(而非变更条数)。
-	seen := map[string]bool{}
-	for _, c := range changes {
-		seen[c.Table] = true
+	tablesAffected := intFromAny(preview["tables_affected"])
+	if tablesAffected == 0 {
+		tablesAffected = len(changes)
 	}
 	est := intFromAny(preview["estimated_seconds"])
 	if est == 0 {
 		est = 30 // PRD 兜底
 	}
 	return map[string]interface{}{
-		"target": target, "tables_affected": len(seen),
+		"target": target, "tables_affected": tablesAffected,
 		"changes": changes, "estimated_seconds": est,
 	}
 }

shortcuts/apps/apps_db_table_get.go

@@ -37,7 +37,7 @@ var AppsDBTableGet = common.Shortcut{
 	Flags: append([]common.Flag{
 		{Name: "app-id", Desc: "app id", Required: true},
 		{Name: "table", Desc: "table name", Required: true},
-	}, dbEnvFlags("", []string{"dev", "online"}, "target db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	}, dbEnvFlags("dev", []string{"dev", "online"}, "target db environment (default dev; use online for the online environment, or for an app whose DB is not multi-env)")...),
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
@@ -80,7 +80,7 @@ var AppsDBTableGet = common.Shortcut{
 // CLI 检测 rctx.Format == "pretty" 时给 server 带 format=ddl，要求返 CREATE 语句文本；
 // 其他 format（含默认 json）不传该参数，让 server 返默认结构化字段。
 func buildDBTableGetParams(rctx *common.RuntimeContext) map[string]interface{} {
-	params := dbEnvParams(rctx, map[string]interface{}{})
+	params := map[string]interface{}{"env": dbEnv(rctx)}
 	if rctx.Format == "pretty" {
 		params["format"] = "ddl"
 	}

shortcuts/apps/apps_db_table_list.go

@@ -8,7 +8,6 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
-	"strconv"
 	"strings"
 
 	"github.com/larksuite/cli/shortcuts/common"
@@ -43,7 +42,7 @@ var AppsDBTableList = common.Shortcut{
 		{Name: "app-id", Desc: "app id", Required: true},
 		{Name: "page-size", Type: "int", Default: "20", Desc: "page size"},
 		{Name: "page-token", Desc: "pagination cursor from previous response"},
-	}, dbEnvFlags("", []string{"dev", "online"}, "target db environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online")...),
+	}, dbEnvFlags("dev", []string{"dev", "online"}, "target db environment (default dev; use online for the online environment, or for an app whose DB is not multi-env)")...),
 	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
 		if _, err := requireAppID(rctx.Str("app-id")); err != nil {
 			return err
@@ -111,9 +110,10 @@ func projectTableListItems(raw interface{}) []dbTableListItem {
 }
 
 func buildDBTableListParams(rctx *common.RuntimeContext) map[string]interface{} {
-	params := dbEnvParams(rctx, map[string]interface{}{
+	params := map[string]interface{}{
+		"env":       dbEnv(rctx),
 		"page_size": rctx.Int("page-size"),
-	})
+	}
 	if token := strings.TrimSpace(rctx.Str("page-token")); token != "" {
 		params["page_token"] = token
 	}
@@ -286,17 +286,6 @@ func numericAsFloat(raw interface{}) (float64, bool) {
 			return 0, false
 		}
 		return f, true
-	case string:
-		// 服务端有些数值字段（如 recovery diff 的 inserted/deleted 行数）以字符串下发。
-		s := strings.TrimSpace(v)
-		if s == "" {
-			return 0, false
-		}
-		f, err := strconv.ParseFloat(s, 64)
-		if err != nil {
-			return 0, false
-		}
-		return f, true
 	case nil:
 		return 0, false
 	}

shortcuts/apps/apps_db_table_list_test.go

@@ -236,11 +236,7 @@ func TestNumericAsFloat_AllTypes(t *testing.T) {
 		{"json.Number valid", json.Number("13.5"), 13.5, true},
 		{"json.Number invalid", json.Number("abc"), 0, false},
 		{"nil", nil, 0, false},
-		{"non-numeric string", "x", 0, false},
-		{"numeric string", "13.5", 13.5, true},
-		{"numeric string int", "2", 2, true},
-		{"numeric string padded", " 13.5 ", 13.5, true},
-		{"empty string", "", 0, false},
+		{"unsupported string", "x", 0, false},
 	}
 	for _, c := range cases {
 		t.Run(c.name, func(t *testing.T) {

shortcuts/apps/db_common.go

@@ -34,16 +34,6 @@ func dbEnv(rctx *common.RuntimeContext) string {
 	return rctx.Str("environment")
 }
 
-// dbEnvParams 把 env 并入 params：仅当显式指定了环境（非空）才带 env 键；未指定（空）时
-// 省略该键，由服务端按应用多环境状态自动选分支（多环境→dev，单环境→online）。与家族对
-// 空可选参数的 omit-empty 约定一致——不发空串，wire 上真正不带 env。原样返回同一个 map 便于链式。
-func dbEnvParams(rctx *common.RuntimeContext, params map[string]interface{}) map[string]interface{} {
-	if env := dbEnv(rctx); env != "" {
-		params["env"] = env
-	}
-	return params
-}
-
 // rejectLegacyEnvFlag 在 Validate 阶段拦截已移除的 --env：显式传了就报清晰的 validation 错，指向 --environment。
 func rejectLegacyEnvFlag(rctx *common.RuntimeContext) error {
 	if rctx.Changed("env") {

shortcuts/base/record_json_shorthand_test.go

@@ -1,73 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package base
-
-import (
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-func mountBaseShortcutFlags(t *testing.T, s common.Shortcut, name string) *cobra.Command {
-	t.Helper()
-	parent := &cobra.Command{Use: "test"}
-	s.Mount(parent, &cmdutil.Factory{})
-	cmd, _, err := parent.Find([]string{name})
-	if err != nil {
-		t.Fatalf("Find(%s) error = %v", name, err)
-	}
-	return cmd
-}
-
-// record-list 获得 --json 简写
-func TestRecordListRegistersJSONShorthand(t *testing.T) {
-	cmd := mountBaseShortcutFlags(t, BaseRecordList, "+record-list")
-	fl := cmd.Flags().Lookup("json")
-	if fl == nil {
-		t.Fatal("+record-list missing --json shorthand")
-	}
-	if fl.Usage != "shorthand for --format json" {
-		t.Errorf("usage = %q, want shorthand", fl.Usage)
-	}
-	if def := cmd.Flags().Lookup("format").DefValue; def != "markdown" {
-		t.Errorf("format default = %q, want markdown (unchanged)", def)
-	}
-}
-
-// record-search / record-get 的 --json 保持请求体语义，不被覆盖（回归锚点）
-func TestRecordSearchGetKeepRequestBodyJSON(t *testing.T) {
-	for _, tc := range []struct {
-		name     string
-		shortcut common.Shortcut
-		cmdName  string
-	}{
-		{"record-search", BaseRecordSearch, "+record-search"},
-		{"record-get", BaseRecordGet, "+record-get"},
-	} {
-		cmd := mountBaseShortcutFlags(t, tc.shortcut, tc.cmdName)
-		fl := cmd.Flags().Lookup("json")
-		if fl == nil {
-			t.Fatalf("%s: --json (request body) missing", tc.name)
-		}
-		if strings.Contains(fl.Usage, "shorthand") {
-			t.Fatalf("%s: request-body --json overwritten by shorthand: %q", tc.name, fl.Usage)
-		}
-		if fl.Value.Type() != "string" {
-			t.Fatalf("%s: --json type = %q, want string", tc.name, fl.Value.Type())
-		}
-	}
-}
-
-// Enum 已接入：help 描述携带枚举后缀（框架对带 Enum 的 flag 自动追加 " (markdown|json)"）
-func TestRecordReadFormatFlagCarriesEnum(t *testing.T) {
-	cmd := mountBaseShortcutFlags(t, BaseRecordList, "+record-list")
-	usage := cmd.Flags().Lookup("format").Usage
-	if !strings.Contains(usage, "(markdown|json)") {
-		t.Fatalf("format usage missing enum suffix: %q", usage)
-	}
-}

shortcuts/base/record_list.go

@@ -85,7 +85,6 @@ func recordReadFormatFlag() common.Flag {
 	return common.Flag{
 		Name:    "format",
 		Default: "markdown",
-		Enum:    []string{"markdown", "json"},
 		Desc:    "output format: markdown (default) | json",
 	}
 }

shortcuts/common/runner.go

@@ -889,7 +889,6 @@ func (s Shortcut) mountDeclarative(ctx context.Context, parent *cobra.Command, f
 		}
 	}
 	cmdmeta.SetSource(cmd, cmdmeta.SourceShortcut, false)
-	cmdmeta.SetAffordanceRef(cmd, shortcut.Service, shortcut.Command)
 	cmdutil.SetSupportedIdentities(cmd, shortcut.AuthTypes)
 	registerShortcutFlagsWithContext(ctx, cmd, f, &shortcut)
 	cmdutil.SetTips(cmd, shortcut.Tips)
@@ -1027,7 +1026,6 @@ func newRuntimeContext(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut, conf
 	}
 	rctx.larkSDK = sdk
 
-	applyJSONShorthand(cmd, s)
 	rctx.Format = rctx.Str("format")
 	rctx.JqExpr, _ = cmd.Flags().GetString("jq")
 	return rctx, nil
@@ -1173,75 +1171,6 @@ func registerShortcutFlags(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut)
 	registerShortcutFlagsWithContext(context.Background(), cmd, f, s)
 }
 
-// shortcutDeclaresJSONFlag reports whether the shortcut itself declares a flag
-// named "json" in its Flags list (custom semantics, e.g. event +subscribe's
-// pretty-print switch or base +record-search's request-body payload).
-// Framework-injected flags never appear in s.Flags, so this cleanly separates
-// "self-declared json" from "injected shorthand".
-func shortcutDeclaresJSONFlag(s *Shortcut) bool {
-	for _, fl := range s.Flags {
-		if fl.Name == "json" {
-			return true
-		}
-	}
-	return false
-}
-
-// shortcutFormatSupportsJSON reports whether the command's format flag accepts
-// "json": a self-declared format supports it only when its Enum lists "json";
-// a framework-injected default format (no format entry in s.Flags) always does.
-func shortcutFormatSupportsJSON(s *Shortcut) bool {
-	for _, fl := range s.Flags {
-		if fl.Name == "format" {
-			return slices.Contains(fl.Enum, "json")
-		}
-	}
-	return true // framework-injected: json (default) | pretty | table | ndjson | csv
-}
-
-// ensureJSONShorthand registers --json as a shorthand for --format json when:
-//  1. the command has a format flag (self-declared or framework-injected), AND
-//  2. that format supports "json" (see shortcutFormatSupportsJSON), AND
-//  3. no flag named "json" is registered yet — pflag panics on duplicate
-//     registration, and commands that declare their own --json (event
-//     +subscribe, base +record-search/-get) keep their custom semantics.
-func ensureJSONShorthand(cmd *cobra.Command, s *Shortcut) {
-	// A shortcut that declares its own "json" flag defines custom semantics
-	// (e.g. pretty-print switch, request-body payload) — never a shorthand.
-	if shortcutDeclaresJSONFlag(s) {
-		return
-	}
-	if cmd.Flags().Lookup("format") == nil {
-		return
-	}
-	if !shortcutFormatSupportsJSON(s) {
-		return
-	}
-	// Safety net: pflag panics on duplicate registration.
-	if cmd.Flags().Lookup("json") != nil {
-		return
-	}
-	cmd.Flags().Bool("json", false, "shorthand for --format json")
-}
-
-// applyJSONShorthand folds the injected --json shorthand into the format flag
-// itself, before rctx.Format caches it — so both the cached value (OutFormat,
-// ValidateJqFlags, dry-run) and later runtime.Str("format") reads observe
-// "json". An explicitly passed --format always wins over the shorthand (the
-// shorthand only fills in when the user did not choose a format). Shortcuts
-// that declare their own "json" flag keep its custom semantics untouched.
-func applyJSONShorthand(cmd *cobra.Command, s *Shortcut) {
-	if shortcutDeclaresJSONFlag(s) {
-		return
-	}
-	if cmd.Flags().Lookup("json") == nil || cmd.Flags().Changed("format") {
-		return
-	}
-	if set, _ := cmd.Flags().GetBool("json"); set {
-		_ = cmd.Flags().Set("format", "json")
-	}
-}
-
 func registerShortcutFlagsWithContext(ctx context.Context, cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut) {
 	for _, fl := range s.Flags {
 		desc := fl.Desc
@@ -1305,8 +1234,10 @@ func registerShortcutFlagsWithContext(ctx context.Context, cmd *cobra.Command, f
 		cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
 			return []string{"json", "pretty", "table", "ndjson", "csv"}, cobra.ShellCompDirectiveNoFileComp
 		})
+		if cmd.Flags().Lookup("json") == nil {
+			cmd.Flags().Bool("json", false, "shorthand for --format json")
+		}
 	}
-	ensureJSONShorthand(cmd, s)
 	if s.Risk == "high-risk-write" {
 		cmd.Flags().Bool("yes", false, "confirm high-risk operation")
 	}

shortcuts/common/runner_json_shorthand_test.go

@@ -1,200 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package common
-
-import (
-	"context"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-)
-
-const jsonShorthandUsage = "shorthand for --format json"
-
-func mountTestShortcut(t *testing.T, s Shortcut) *cobra.Command {
-	t.Helper()
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	parent := &cobra.Command{Use: "root"}
-	s.Mount(parent, f)
-	cmd, _, err := parent.Find([]string{s.Command})
-	if err != nil {
-		t.Fatalf("Find() error = %v", err)
-	}
-	return cmd
-}
-
-// 自定义 format 且 Enum 含 json → 注册简写（本次修复的核心行为）
-func TestJSONShorthand_CustomFormatWithJSONEnum_Registered(t *testing.T) {
-	cmd := mountTestShortcut(t, Shortcut{
-		Service: "mail", Command: "+fake-triage", Description: "x",
-		Flags:   []Flag{{Name: "format", Default: "table", Enum: []string{"table", "json", "data"}, Desc: "fmt"}},
-		Execute: func(context.Context, *RuntimeContext) error { return nil },
-	})
-	fl := cmd.Flags().Lookup("json")
-	if fl == nil {
-		t.Fatal("--json not registered for custom-format shortcut whose Enum contains json")
-	}
-	if fl.Usage != jsonShorthandUsage {
-		t.Errorf("usage = %q, want %q", fl.Usage, jsonShorthandUsage)
-	}
-	// 默认输出格式不被改变
-	if def := cmd.Flags().Lookup("format").DefValue; def != "table" {
-		t.Errorf("format default = %q, want table", def)
-	}
-}
-
-// 自定义 format 但 Enum 不含 json → 不注册
-func TestJSONShorthand_CustomFormatWithoutJSONEnum_NotRegistered(t *testing.T) {
-	cmd := mountTestShortcut(t, Shortcut{
-		Service: "x", Command: "+no-json", Description: "x",
-		Flags:   []Flag{{Name: "format", Default: "csv", Enum: []string{"csv", "table"}, Desc: "fmt"}},
-		Execute: func(context.Context, *RuntimeContext) error { return nil },
-	})
-	if cmd.Flags().Lookup("json") != nil {
-		t.Fatal("--json must NOT be registered when format Enum lacks json")
-	}
-}
-
-// 自定义 format 但无 Enum（现状 triage 形态）→ 不注册（Enum 是判定依据）
-func TestJSONShorthand_CustomFormatNoEnum_NotRegistered(t *testing.T) {
-	cmd := mountTestShortcut(t, Shortcut{
-		Service: "x", Command: "+legacy", Description: "x",
-		Flags:   []Flag{{Name: "format", Default: "table", Desc: "fmt"}},
-		Execute: func(context.Context, *RuntimeContext) error { return nil },
-	})
-	if cmd.Flags().Lookup("json") != nil {
-		t.Fatal("--json must NOT be registered when format has no Enum metadata")
-	}
-}
-
-// 自声明 json flag（subscribe 的 pretty / record-search 的请求体）→ 不覆盖、不 panic、语义保留
-func TestJSONShorthand_SelfDeclaredJSON_Preserved(t *testing.T) {
-	cmd := mountTestShortcut(t, Shortcut{
-		Service: "event", Command: "+fake-subscribe", Description: "x",
-		Flags: []Flag{
-			{Name: "json", Type: "bool", Desc: "pretty-print JSON instead of NDJSON"},
-		},
-		Execute: func(context.Context, *RuntimeContext) error { return nil },
-	})
-	fl := cmd.Flags().Lookup("json")
-	if fl == nil {
-		t.Fatal("self-declared --json missing")
-	}
-	if fl.Usage != "pretty-print JSON instead of NDJSON" {
-		t.Errorf("self-declared --json usage overwritten: %q", fl.Usage)
-	}
-}
-
-// parseMounted mounts the shortcut and parses args against the command's FlagSet
-// (registration side effects included), without executing RunE.
-func parseMounted(t *testing.T, s Shortcut, args []string) *cobra.Command {
-	t.Helper()
-	cmd := mountTestShortcut(t, s)
-	if err := cmd.ParseFlags(args); err != nil {
-		t.Fatalf("ParseFlags(%v) error = %v", args, err)
-	}
-	return cmd
-}
-
-func customFormatShortcut() Shortcut {
-	return Shortcut{
-		Service: "mail", Command: "+fake-triage", Description: "x",
-		Flags:   []Flag{{Name: "format", Default: "table", Enum: []string{"table", "json", "data"}, Desc: "fmt"}},
-		Execute: func(context.Context, *RuntimeContext) error { return nil },
-	}
-}
-
-// --json 单独使用 → format 归一化为 json
-func TestApplyJSONShorthand_JSONAlone_SetsFormatJSON(t *testing.T) {
-	s := customFormatShortcut()
-	cmd := parseMounted(t, s, []string{"--json"})
-	applyJSONShorthand(cmd, &s)
-	if got := cmd.Flags().Lookup("format").Value.String(); got != "json" {
-		t.Fatalf("format = %q, want json", got)
-	}
-}
-
-// 显式 --format 优先于 --json 简写：--format table --json → table
-func TestApplyJSONShorthand_ExplicitFormatWins(t *testing.T) {
-	s := customFormatShortcut()
-	cmd := parseMounted(t, s, []string{"--format", "table", "--json"})
-	applyJSONShorthand(cmd, &s)
-	if got := cmd.Flags().Lookup("format").Value.String(); got != "table" {
-		t.Fatalf("format = %q, want table (explicit --format must win)", got)
-	}
-}
-
-// --format json --json → json（一致，无冲突）
-func TestApplyJSONShorthand_ExplicitJSONFormatConsistent(t *testing.T) {
-	s := customFormatShortcut()
-	cmd := parseMounted(t, s, []string{"--format", "json", "--json"})
-	applyJSONShorthand(cmd, &s)
-	if got := cmd.Flags().Lookup("format").Value.String(); got != "json" {
-		t.Fatalf("format = %q, want json", got)
-	}
-}
-
-// 均不传 → 默认值不变
-func TestApplyJSONShorthand_NoFlags_DefaultUntouched(t *testing.T) {
-	s := customFormatShortcut()
-	cmd := parseMounted(t, s, nil)
-	applyJSONShorthand(cmd, &s)
-	if got := cmd.Flags().Lookup("format").Value.String(); got != "table" {
-		t.Fatalf("format = %q, want table (default untouched)", got)
-	}
-}
-
-// 自声明 string 型 --json（record-search 形态：format+json 双声明）→ 归一化跳过
-func TestApplyJSONShorthand_SelfDeclaredStringJSON_Skipped(t *testing.T) {
-	s := Shortcut{
-		Service: "base", Command: "+fake-record-search", Description: "x",
-		Flags: []Flag{
-			{Name: "format", Default: "markdown", Enum: []string{"markdown", "json"}, Desc: "fmt"},
-			{Name: "json", Desc: "request body JSON object"},
-		},
-		Execute: func(context.Context, *RuntimeContext) error { return nil },
-	}
-	cmd := parseMounted(t, s, []string{"--json", `{"keyword":"Alice"}`})
-	applyJSONShorthand(cmd, &s)
-	if got := cmd.Flags().Lookup("format").Value.String(); got != "markdown" {
-		t.Fatalf("format = %q, want markdown (self-declared json must not normalize)", got)
-	}
-	if got := cmd.Flags().Lookup("json").Value.String(); got != `{"keyword":"Alice"}` {
-		t.Fatalf("request-body --json corrupted: %q", got)
-	}
-}
-
-// 自声明 bool 型 --json（subscribe 形态：无自定义 format，框架注入 format）→ 归一化跳过
-func TestApplyJSONShorthand_SelfDeclaredBoolJSON_Skipped(t *testing.T) {
-	s := Shortcut{
-		Service: "event", Command: "+fake-subscribe", Description: "x",
-		Flags: []Flag{
-			{Name: "json", Type: "bool", Desc: "pretty-print JSON instead of NDJSON"},
-		},
-		Execute: func(context.Context, *RuntimeContext) error { return nil },
-	}
-	cmd := parseMounted(t, s, []string{"--json"})
-	applyJSONShorthand(cmd, &s)
-	// 注入的 format 默认即 json；这里断言的是 Changed 状态未被归一化污染
-	if cmd.Flags().Changed("format") {
-		t.Fatal("normalization must not touch format for shortcuts declaring their own --json")
-	}
-}
-
-// 无自定义 format（普通命令）→ 注入默认 format + 简写（现状回归）
-func TestJSONShorthand_DefaultInjectedFormat_StillRegistered(t *testing.T) {
-	cmd := mountTestShortcut(t, Shortcut{
-		Service: "im", Command: "+plain", Description: "x",
-		Execute: func(context.Context, *RuntimeContext) error { return nil },
-	})
-	fl := cmd.Flags().Lookup("json")
-	if fl == nil {
-		t.Fatal("--json missing on default-format shortcut (regression)")
-	}
-	if fl.Usage != jsonShorthandUsage {
-		t.Errorf("usage = %q, want %q", fl.Usage, jsonShorthandUsage)
-	}
-}

shortcuts/contact/contact_search_user.go

@@ -150,10 +150,12 @@ var ContactSearchUser = common.Shortcut{
 		{Name: "queries", Desc: "comma-separated keywords searched in parallel; output is a flat users[] with matched_query plus a queries[] sidecar"},
 	},
 	Tips: []string{
+		"Keyword search: lark-cli contact +search-user --query 'alice'",
+		"Look up by ID (or 'me' for self): lark-cli contact +search-user --user-ids 'ou_xxx,me'",
 		"Filter-only enumeration — users you've chatted with: lark-cli contact +search-user --has-chatted",
 		"Refine same-name hits: lark-cli contact +search-user --query '张三' --has-chatted --exclude-external-users",
 		"Multi-name fanout: lark-cli contact +search-user --queries 'alice,bob,张三'",
-		"on has_more=true add filters or tighten --query — there is no auto-pagination.",
+		"open_id is the stable identifier for follow-up commands; on has_more=true add filters or tighten --query — there is no auto-pagination.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return validateSearchUser(runtime)

shortcuts/mail/mail_json_shorthand_test.go

@@ -1,112 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package mail
-
-import (
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-)
-
-// help 必须列出 --json 简写
-func TestMailTriageHelpListsJSONShorthand(t *testing.T) {
-	f, stdout, _, _ := mailShortcutTestFactory(t)
-	if err := runMountedMailShortcutWithCobraOutput(t, MailTriage, []string{"+triage", "-h"}, f, stdout); err != nil {
-		t.Fatalf("help returned error: %v", err)
-	}
-	if !strings.Contains(stdout.String(), "shorthand for --format json") {
-		t.Fatalf("triage help missing --json shorthand\n%s", stdout.String())
-	}
-}
-
-func TestMailWatchHelpListsJSONShorthand(t *testing.T) {
-	f, stdout, _, _ := mailShortcutTestFactory(t)
-	if err := runMountedMailShortcutWithCobraOutput(t, MailWatch, []string{"+watch", "-h"}, f, stdout); err != nil {
-		t.Fatalf("help returned error: %v", err)
-	}
-	if !strings.Contains(stdout.String(), "shorthand for --format json") {
-		t.Fatalf("watch help missing --json shorthand\n%s", stdout.String())
-	}
-}
-
-// 行为验证：--json 走 JSON 输出路径，不输出 table read hint
-func TestMailTriageJSONShorthandDoesNotEmitReadHint(t *testing.T) {
-	f, stdout, stderr, reg := mailShortcutTestFactory(t)
-	registerTriageReadHintStubs(reg)
-
-	err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--json", "--max", "1"}, f, stdout)
-	if err != nil {
-		t.Fatalf("triage --json returned error: %v", err)
-	}
-	reg.Verify(t)
-	if strings.Contains(stderr.String(), "tip: read full content:") {
-		t.Fatalf("--json must follow the JSON path, got table hint\nstderr=%s", stderr.String())
-	}
-	if !strings.Contains(stdout.String(), `"messages"`) {
-		t.Fatalf("--json stdout missing JSON payload\n%s", stdout.String())
-	}
-}
-
-// 等价性验证：--json 与 --format json 的 dry-run 输出一致
-func TestMailTriageJSONShorthandDryRunEquivalence(t *testing.T) {
-	f1, stdout1, _, _ := mailShortcutTestFactory(t)
-	if err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--json", "--max", "1", "--dry-run"}, f1, stdout1); err != nil {
-		t.Fatalf("--json --dry-run error: %v", err)
-	}
-	f2, stdout2, _, _ := mailShortcutTestFactory(t)
-	if err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--format", "json", "--max", "1", "--dry-run"}, f2, stdout2); err != nil {
-		t.Fatalf("--format json --dry-run error: %v", err)
-	}
-	if stdout1.String() != stdout2.String() {
-		t.Fatalf("dry-run outputs differ:\n--json:\n%s\n--format json:\n%s", stdout1.String(), stdout2.String())
-	}
-}
-
-// 优先级验证：显式 --format table 优先，--json 让位 → 仍走 table 路径
-func TestMailTriageExplicitTableWinsOverJSONShorthand(t *testing.T) {
-	f, stdout, stderr, reg := mailShortcutTestFactory(t)
-	registerTriageReadHintStubs(reg)
-
-	err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--format", "table", "--json", "--max", "1"}, f, stdout)
-	if err != nil {
-		t.Fatalf("triage returned error: %v", err)
-	}
-	if !strings.Contains(stderr.String(), "tip: read full content:") {
-		t.Fatalf("explicit --format table must win over --json (expected table hint)\nstderr=%s", stderr.String())
-	}
-}
-
-// 错误验证：Enum 硬校验
-func TestMailTriageEnumRejectsUnknownFormat(t *testing.T) {
-	f, stdout, _, _ := mailShortcutTestFactory(t)
-	err := runMountedMailShortcut(t, MailTriage, []string{"+triage", "--format", "bogus", "--max", "1", "--dry-run"}, f, stdout)
-	if err == nil {
-		t.Fatal("expected validation error for --format bogus")
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("error = %T, want typed errs problem carrier", err)
-	}
-	if problem.Category != errs.CategoryValidation {
-		t.Fatalf("category = %q, want %q", problem.Category, errs.CategoryValidation)
-	}
-	if problem.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype = %q, want %q", problem.Subtype, errs.SubtypeInvalidArgument)
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("error = %T, want *errs.ValidationError", err)
-	}
-	if ve.Param != "--format" {
-		t.Fatalf("param = %q, want --format", ve.Param)
-	}
-	if !strings.Contains(problem.Message, `invalid value "bogus" for --format`) {
-		t.Fatalf("message = %q, want enum validation message", problem.Message)
-	}
-	if !strings.Contains(problem.Message, "table, json, data") {
-		t.Fatalf("message = %q, want allowed values list", problem.Message)
-	}
-}

shortcuts/mail/mail_triage.go

@@ -55,7 +55,7 @@ var MailTriage = common.Shortcut{
 	Scopes:      []string{"mail:user_mailbox.message:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
 	AuthTypes:   []string{"user", "bot"},
 	Flags: []common.Flag{
-		{Name: "format", Default: "table", Enum: []string{"table", "json", "data"}, Desc: "output format: table | json | data (json/data output object with pagination fields)"},
+		{Name: "format", Default: "table", Desc: "output format: table | json | data (json/data output object with pagination fields)"},
 		{Name: "max", Type: "int", Default: "20", Desc: "maximum number of messages to fetch (1-400; auto-paginates internally)"},
 		{Name: "page-size", Type: "int", Desc: "alias for --max"},
 		{Name: "page-token", Desc: "pagination token from a previous response to fetch the next page"},

shortcuts/mail/mail_watch.go

@@ -99,7 +99,7 @@ var MailWatch = common.Shortcut{
 	Scopes:      []string{"mail:event", "mail:user_mailbox.event.mail_address:read", "mail:user_mailbox:readonly", "mail:user_mailbox.message:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
 	AuthTypes:   []string{"user"},
 	Flags: []common.Flag{
-		{Name: "format", Default: "data", Enum: []string{"json", "data"}, Desc: "json: NDJSON stream with ok/data envelope; data: bare NDJSON stream"},
+		{Name: "format", Default: "data", Desc: "json: NDJSON stream with ok/data envelope; data: bare NDJSON stream"},
 		{Name: "msg-format", Default: "metadata", Desc: "message payload mode: metadata(headers + meta, for triage/notification) | minimal(IDs and state only, no headers, for tracking read/folder changes) | plain_text_full(all metadata fields + full plain-text body) | event(raw WebSocket event, no API call, for debug) | full(full message including HTML body and attachments)"},
 		{Name: "output-dir", Desc: "Write each message as a JSON file (always full payload, regardless of --msg-format)"},
 		{Name: "mailbox", Default: "me", Desc: "email address (default: me)"},

shortcuts/vc/vc_meeting_events.go

@@ -5,7 +5,6 @@ package vc
 
 import (
 	"context"
-	"encoding/json"
 	"fmt"
 	"io"
 	"net/http"
@@ -16,7 +15,6 @@ import (
 	"unicode"
 
 	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -27,9 +25,6 @@ const (
 	minVCMeetingEventsPageSize = 20
 	maxVCMeetingEventsPageSize = 100
 	maxVCMeetingEventsPages    = 200
-	leaveReasonUserLeft        = 1
-	leaveReasonMeetingEnded    = 2
-	leaveReasonKicked          = 3
 )
 
 var meetingDisplayLocation = time.FixedZone("UTC+8", 8*60*60)
@@ -46,11 +41,11 @@ func toUnixSeconds(input string, hint ...string) (string, error) {
 	return ts, nil
 }
 
-// VCMeetingEvents lists meeting events for a meeting.
+// VCMeetingEvents lists bot meeting events for a meeting.
 var VCMeetingEvents = common.Shortcut{
 	Service:     "vc",
 	Command:     "+meeting-events",
-	Description: "List meeting events by meeting ID",
+	Description: "List bot meeting events by meeting ID",
 	Risk:        "read",
 	Scopes:      []string{"vc:meeting.meetingevent:read"},
 	AuthTypes:   []string{"user", "bot"},
@@ -104,28 +99,20 @@ var VCMeetingEvents = common.Shortcut{
 			return err
 		}
 		events = compactMeetingEvents(events)
-		identity, identityWarning := meetingEventsCurrentIdentity(runtime)
-		outData := buildMeetingEventsOutput(data, events, identity, identityWarning)
-		metadata := map[string]interface{}{
-			"row_type":   "metadata",
-			"meeting":    outData.Meeting,
-			"identity":   outData.Identity,
-			"has_more":   outData.HasMore,
-			"page_token": outData.PageToken,
+		outData := map[string]interface{}{
+			"events":     events,
+			"has_more":   data["has_more"],
+			"page_token": data["page_token"],
 		}
-		if len(outData.Warnings) > 0 {
-			metadata["warnings"] = outData.Warnings
-		}
-		ndjsonData := meetingEventsEventRows(outData.Events, metadata)
 
 		timeline := buildMeetingEventTimeline(events)
-		if runtime.Format == "ndjson" {
-			runtime.OutFormat(ndjsonData, &output.Meta{Count: len(events)}, func(w io.Writer) {})
-		} else {
-			runtime.OutFormat(outData, &output.Meta{Count: len(events)}, func(w io.Writer) {
-				renderMeetingEventsCompactPretty(w, outData, timeline)
-			})
-		}
+		runtime.OutFormat(outData, &output.Meta{Count: len(events)}, func(w io.Writer) {
+			if len(timeline.entries) == 0 {
+				fmt.Fprintln(w, "No meeting events.")
+				return
+			}
+			io.WriteString(w, renderMeetingEventsPretty(timeline))
+		})
 		if runtime.Format == "pretty" && pageToken != "" {
 			fmt.Fprintf(runtime.IO().Out, "\npage_token: %s\n", pageToken)
 			if hasMore {
@@ -136,400 +123,6 @@ var VCMeetingEvents = common.Shortcut{
 	},
 }
 
-type meetingEventsOutput struct {
-	Meeting   meetingEventsMeeting  `json:"meeting"`
-	Identity  meetingEventsIdentity `json:"identity"`
-	Events    []meetingEventsEvent  `json:"events"`
-	Warnings  []string              `json:"warnings,omitempty"`
-	HasMore   bool                  `json:"has_more"`
-	PageToken string                `json:"page_token,omitempty"`
-}
-
-type meetingEventsMeeting struct {
-	ID        string `json:"id,omitempty"`
-	Topic     string `json:"topic,omitempty"`
-	MeetingNo string `json:"meeting_no,omitempty"`
-	StartTime string `json:"start_time,omitempty"`
-	EndTime   string `json:"end_time,omitempty"`
-	Status    string `json:"status"`
-}
-
-type meetingEventsIdentity struct {
-	ID              string `json:"id,omitempty"`
-	Name            string `json:"name,omitempty"`
-	ParticipantType string `json:"participant_type,omitempty"`
-	Role            string `json:"role,omitempty"`
-	Label           string `json:"label,omitempty"`
-}
-
-type meetingEventsEvent struct {
-	EventID   string                  `json:"event_id,omitempty"`
-	EventType string                  `json:"event_type,omitempty"`
-	EventTime string                  `json:"event_time,omitempty"`
-	Actors    []meetingEventsIdentity `json:"actors,omitempty"`
-	Payload   map[string]interface{}  `json:"payload,omitempty"`
-}
-
-type meetingEventsEndSignal struct {
-	Ended      bool
-	EndTime    time.Time
-	HasEndTime bool
-}
-
-func buildMeetingEventsOutput(data map[string]interface{}, events []interface{}, identity meetingEventsIdentity, warnings ...string) meetingEventsOutput {
-	output := meetingEventsOutput{
-		Meeting:   meetingEventsMeetingFromPayload(nil),
-		Identity:  identity,
-		HasMore:   common.GetBool(data, "has_more"),
-		PageToken: common.GetString(data, "page_token"),
-	}
-	for _, warning := range warnings {
-		if warning = strings.TrimSpace(warning); warning != "" {
-			output.Warnings = append(output.Warnings, warning)
-		}
-	}
-	for _, raw := range events {
-		event, _ := raw.(map[string]interface{})
-		if event == nil {
-			continue
-		}
-		payload := common.GetMap(event, "payload")
-		if meeting := common.GetMap(payload, "meeting"); meeting != nil {
-			output.Meeting = meetingEventsMeetingFromPayload(meeting)
-		}
-		output.Events = append(output.Events, meetingEventsEventFromPayload(event, output.Identity))
-	}
-	applyMeetingEventsEndSignal(&output.Meeting, meetingEventsEndSignalFromEvents(events))
-	return output
-}
-
-func meetingEventsCurrentIdentity(runtime *common.RuntimeContext) (meetingEventsIdentity, string) {
-	if runtime.As() == core.AsBot {
-		botInfo, err := runtime.BotInfo()
-		if err != nil {
-			return meetingEventsBotIdentity(nil), fmt.Sprintf("identity unavailable: %v", err)
-		}
-		return meetingEventsBotIdentity(botInfo), ""
-	}
-	userOpenID := strings.TrimSpace(runtime.UserOpenId())
-	identity := meetingEventsIdentity{
-		ID:              userOpenID,
-		Name:            strings.TrimSpace(runtime.Config.UserName),
-		ParticipantType: "human",
-	}
-	identity.Label = identityLabel(identity)
-	if userOpenID == "" {
-		return identity, "identity unavailable: current user open_id is unavailable"
-	}
-	return identity, ""
-}
-
-func meetingEventsBotIdentity(botInfo *common.BotInfo) meetingEventsIdentity {
-	if botInfo == nil {
-		return meetingEventsIdentity{ParticipantType: "bot", Label: "bot"}
-	}
-	identity := meetingEventsIdentity{
-		ID:              botInfo.OpenID,
-		Name:            botInfo.AppName,
-		ParticipantType: "bot",
-	}
-	identity.Label = identityLabel(identity)
-	return identity
-}
-
-func meetingEventsMeetingFromPayload(meeting map[string]interface{}) meetingEventsMeeting {
-	out := meetingEventsMeeting{
-		ID:        common.GetString(meeting, "id"),
-		Topic:     common.GetString(meeting, "topic"),
-		MeetingNo: common.GetString(meeting, "meeting_no"),
-		StartTime: meetingEventsTimeString(common.GetString(meeting, "start_time")),
-		EndTime:   meetingEventsTimeString(common.GetString(meeting, "end_time")),
-		Status:    "unknown",
-	}
-	start, hasStart := parseFlexibleTime(out.StartTime)
-	end, hasEnd := parseFlexibleTime(out.EndTime)
-	if hasStart && !hasEnd {
-		out.Status = "ongoing"
-	}
-	if hasStart && hasEnd {
-		if end.After(start) {
-			out.Status = "ended"
-		} else {
-			out.Status = "ongoing"
-			out.EndTime = ""
-		}
-	}
-	return out
-}
-
-func applyMeetingEventsEndSignal(meeting *meetingEventsMeeting, signal meetingEventsEndSignal) {
-	if meeting == nil || !signal.Ended {
-		return
-	}
-	meeting.Status = "ended"
-	if signal.HasEndTime {
-		meeting.EndTime = signal.EndTime.UTC().Format(time.RFC3339)
-	}
-}
-
-func meetingEventsEndSignalFromEvents(events []interface{}) meetingEventsEndSignal {
-	var signal meetingEventsEndSignal
-	for _, raw := range events {
-		event, _ := raw.(map[string]interface{})
-		if event == nil || meetingEventType(event) != "participant_left" {
-			continue
-		}
-		payload := common.GetMap(event, "payload")
-		if payload == nil {
-			continue
-		}
-		fallbackTime, fallbackOK := parseFlexibleTime(common.GetString(event, "event_time"))
-		for _, rawItem := range common.GetSlice(payload, "participant_left_items") {
-			item, _ := rawItem.(map[string]interface{})
-			if item == nil || int(common.GetFloat(item, "leave_reason")) != leaveReasonMeetingEnded {
-				continue
-			}
-			signal.Ended = true
-			endTime, ok := parseFlexibleTime(common.GetString(item, "leave_time"))
-			if !ok {
-				endTime, ok = fallbackTime, fallbackOK
-			}
-			if ok && (!signal.HasEndTime || endTime.After(signal.EndTime)) {
-				signal.EndTime = endTime
-				signal.HasEndTime = true
-			}
-		}
-	}
-	return signal
-}
-
-func meetingEventsEventFromPayload(event map[string]interface{}, selfIdentity meetingEventsIdentity) meetingEventsEvent {
-	payload := common.GetMap(event, "payload")
-	out := meetingEventsEvent{
-		EventID:   common.GetString(event, "event_id"),
-		EventType: meetingEventType(event),
-		EventTime: meetingEventsTimeString(common.GetString(event, "event_time")),
-		Payload:   payload,
-	}
-	out.Actors = eventActors(out.EventType, payload, selfIdentity)
-	return out
-}
-
-func eventActors(eventType string, payload map[string]interface{}, selfIdentity meetingEventsIdentity) []meetingEventsIdentity {
-	var actors []meetingEventsIdentity
-	addFromItems := func(key, participantKey string) {
-		for _, raw := range common.GetSlice(payload, key) {
-			item, _ := raw.(map[string]interface{})
-			if item == nil {
-				continue
-			}
-			if participant := common.GetMap(item, participantKey); participant != nil {
-				actors = append(actors, meetingEventsIdentityFromParticipant(participant, selfIdentity))
-			}
-		}
-	}
-	switch eventType {
-	case "participant_joined":
-		addFromItems("participant_joined_items", "participant")
-	case "participant_left":
-		addFromItems("participant_left_items", "participant")
-	case "transcript_received":
-		addFromItems("transcript_received_items", "speaker")
-	case "chat_received":
-		addFromItems("chat_received_items", "operator")
-	case "magic_share_started":
-		addFromItems("magic_share_started_items", "operator")
-	case "magic_share_ended":
-		addFromItems("magic_share_ended_items", "operator")
-	}
-	return actors
-}
-
-func meetingEventsIdentityFromParticipant(participant map[string]interface{}, selfIdentity meetingEventsIdentity) meetingEventsIdentity {
-	identity := meetingEventsIdentity{
-		ID:              common.GetString(participant, "id"),
-		Name:            common.GetString(participant, "user_name"),
-		ParticipantType: meetingEventsParticipantType(participant),
-		Role:            meetingEventsParticipantRole(participant),
-	}
-	if identity.ID != "" && selfIdentity.ID != "" && identity.ID == selfIdentity.ID {
-		if selfIdentity.ParticipantType == "bot" && (identity.ParticipantType == "" || identity.ParticipantType == "human") {
-			identity.ParticipantType = "bot"
-		}
-		if selfIdentity.ParticipantType == "bot" && (identity.Role == "" || identity.Role == "participant") {
-			identity.Role = "bot"
-		}
-	}
-	if identity.ParticipantType == "" {
-		identity.ParticipantType = "human"
-	}
-	if identity.Role == "" {
-		identity.Role = "participant"
-	}
-	identity.Label = identityLabel(identity)
-	return identity
-}
-
-func meetingEventsParticipantType(participant map[string]interface{}) string {
-	if raw := meetingEventsParticipantTypeFromParticipantType(fieldValueString(participant, "participant_type")); raw != "" {
-		return raw
-	}
-	return meetingEventsParticipantTypeFromUserType(fieldValueString(participant, "user_type"))
-}
-
-func meetingEventsParticipantTypeFromParticipantType(raw string) string {
-	raw = strings.ToLower(strings.TrimSpace(raw))
-	switch raw {
-	case "1", "user", "human":
-		return "human"
-	case "2", "bot", "app":
-		return "bot"
-	case "":
-		return ""
-	default:
-		return "unknown"
-	}
-}
-
-func meetingEventsParticipantRole(participant map[string]interface{}) string {
-	if raw := meetingEventsRoleFromParticipantRole(fieldValueString(participant, "role")); raw != "" {
-		return raw
-	}
-	return meetingEventsRoleFromEventUserRole(fieldValueString(participant, "user_role"))
-}
-
-func meetingEventsParticipantTypeFromUserType(raw string) string {
-	raw = strings.ToLower(strings.TrimSpace(raw))
-	switch raw {
-	case "1", "user", "human":
-		return "human"
-	case "2", "10", "bot", "app":
-		return "bot"
-	case "":
-		return ""
-	default:
-		return "unknown"
-	}
-}
-
-func meetingEventsRoleFromParticipantRole(raw string) string {
-	raw = strings.ToLower(strings.TrimSpace(raw))
-	switch raw {
-	case "1", "host":
-		return "host"
-	case "2", "co_host", "cohost":
-		return "co_host"
-	case "3", "participant", "attendee":
-		return "participant"
-	case "4", "bot", "app":
-		return "bot"
-	case "":
-		return ""
-	default:
-		return raw
-	}
-}
-
-func meetingEventsRoleFromEventUserRole(raw string) string {
-	raw = strings.ToLower(strings.TrimSpace(raw))
-	switch raw {
-	case "1", "participant", "attendee":
-		return "participant"
-	case "2", "host":
-		return "host"
-	case "4", "bot", "app":
-		return "bot"
-	case "", "0":
-		return ""
-	default:
-		return raw
-	}
-}
-
-func fieldValueString(values map[string]interface{}, key string) string {
-	if values == nil {
-		return ""
-	}
-	switch value := values[key].(type) {
-	case string:
-		return value
-	case int:
-		return strconv.Itoa(value)
-	case int64:
-		return strconv.FormatInt(value, 10)
-	case float64:
-		return strconv.FormatInt(int64(value), 10)
-	case json.Number:
-		return value.String()
-	default:
-		return ""
-	}
-}
-
-func identityLabel(identity meetingEventsIdentity) string {
-	name := identity.Name
-	if name == "" {
-		name = identity.ID
-	}
-	if name == "" {
-		name = "unknown"
-	}
-	var tags []string
-	if identity.ParticipantType != "" {
-		tags = append(tags, identity.ParticipantType)
-	}
-	if identity.Role != "" && identity.Role != identity.ParticipantType {
-		tags = append(tags, identity.Role)
-	}
-	if len(tags) == 0 {
-		return name
-	}
-	return fmt.Sprintf("%s [%s]", name, strings.Join(tags, ","))
-}
-
-func meetingEventsTimeString(raw string) string {
-	if parsed, ok := parseFlexibleTime(raw); ok {
-		return parsed.UTC().Format(time.RFC3339)
-	}
-	return strings.TrimSpace(raw)
-}
-
-func meetingEventsEventRows(events []meetingEventsEvent, metadata map[string]interface{}) []interface{} {
-	rows := make([]interface{}, 0, len(events)+1)
-	for _, event := range events {
-		row := meetingEventsEventRow(event)
-		rows = append(rows, row)
-	}
-	if metadata != nil {
-		rows = append(rows, metadata)
-	}
-	return rows
-}
-
-func meetingEventsEventRow(event meetingEventsEvent) map[string]interface{} {
-	raw, err := json.Marshal(event)
-	if err != nil {
-		return map[string]interface{}{"row_type": "event"}
-	}
-	var row map[string]interface{}
-	if err := json.Unmarshal(raw, &row); err != nil {
-		return map[string]interface{}{"row_type": "event"}
-	}
-	row["row_type"] = "event"
-	return row
-}
-
-func renderMeetingEventsCompactPretty(w io.Writer, data meetingEventsOutput, timeline meetingTimeline) {
-	if data.Identity.Label != "" {
-		fmt.Fprintf(w, "当前身份：%s\n", escapePrettyText(data.Identity.Label))
-	}
-	if len(timeline.entries) == 0 {
-		fmt.Fprintln(w, "No meeting events.")
-		return
-	}
-	io.WriteString(w, renderMeetingEventsPretty(timeline))
-}
-
 func meetingEventsPageSize(runtime *common.RuntimeContext) (int, error) {
 	if runtime.Bool("page-all") {
 		return maxVCMeetingEventsPageSize, nil
@@ -730,6 +323,7 @@ type meetingTimelineEntry struct {
 	when        time.Time
 	hasWhen     bool
 	sequence    int
+	group       int
 	subject     string
 	description string
 	details     []string
@@ -738,6 +332,7 @@ type meetingTimelineEntry struct {
 func buildMeetingEventTimeline(events []interface{}) meetingTimeline {
 	timeline := meetingTimeline{}
 	var sequence int
+	var group int
 	for _, raw := range events {
 		event, _ := raw.(map[string]interface{})
 		if event == nil {
@@ -750,11 +345,11 @@ func buildMeetingEventTimeline(events []interface{}) meetingTimeline {
 		if timeline.topic == "" || !timeline.hasStart || !timeline.hasEnd {
 			populateMeetingHeader(&timeline, common.GetMap(payload, "meeting"))
 		}
-		for _, entry := range buildTimelineEntriesForEvent(event, &sequence) {
+		for _, entry := range buildTimelineEntriesForEvent(event, &sequence, group) {
 			timeline.entries = append(timeline.entries, entry)
 		}
+		group++
 	}
-	applyMeetingTimelineEndSignal(&timeline, meetingEventsEndSignalFromEvents(events))
 	sort.SliceStable(timeline.entries, func(i, j int) bool {
 		left := timeline.entries[i]
 		right := timeline.entries[j]
@@ -775,24 +370,6 @@ func buildMeetingEventTimeline(events []interface{}) meetingTimeline {
 	return timeline
 }
 
-func applyMeetingTimelineEndSignal(timeline *meetingTimeline, signal meetingEventsEndSignal) {
-	if timeline == nil || !signal.Ended {
-		return
-	}
-	if signal.HasEndTime {
-		if !timeline.hasStart || signal.EndTime.After(timeline.startTime) {
-			timeline.endTime = signal.EndTime
-			timeline.hasEnd = true
-			return
-		}
-		timeline.hasEnd = false
-		return
-	}
-	if timeline.hasStart && timeline.hasEnd && !timeline.endTime.After(timeline.startTime) {
-		timeline.hasEnd = false
-	}
-}
-
 func populateMeetingHeader(timeline *meetingTimeline, meeting map[string]interface{}) {
 	if timeline == nil || meeting == nil {
 		return
@@ -814,7 +391,7 @@ func populateMeetingHeader(timeline *meetingTimeline, meeting map[string]interfa
 	}
 }
 
-func buildTimelineEntriesForEvent(event map[string]interface{}, sequence *int) []meetingTimelineEntry {
+func buildTimelineEntriesForEvent(event map[string]interface{}, sequence *int, group int) []meetingTimelineEntry {
 	payload := common.GetMap(event, "payload")
 	if payload == nil {
 		return nil
@@ -823,26 +400,26 @@ func buildTimelineEntriesForEvent(event map[string]interface{}, sequence *int) [
 	eventTime, eventTimeOK := parseFlexibleTime(common.GetString(event, "event_time"))
 	switch eventType {
 	case "participant_joined":
-		return participantJoinedEntries(payload, eventTime, eventTimeOK, sequence)
+		return participantJoinedEntries(payload, eventTime, eventTimeOK, sequence, group)
 	case "participant_left":
-		return participantLeftEntries(payload, eventTime, eventTimeOK, sequence)
+		return participantLeftEntries(payload, eventTime, eventTimeOK, sequence, group)
 	case "transcript_received":
-		return transcriptEntries(payload, eventTime, eventTimeOK, sequence)
+		return transcriptEntries(payload, eventTime, eventTimeOK, sequence, group)
 	case "chat_received":
-		return chatEntries(payload, eventTime, eventTimeOK, sequence)
+		return chatEntries(payload, eventTime, eventTimeOK, sequence, group)
 	case "magic_share_started":
-		return magicShareStartedEntries(payload, eventTime, eventTimeOK, sequence)
+		return magicShareStartedEntries(payload, eventTime, eventTimeOK, sequence, group)
 	case "magic_share_ended":
-		return magicShareEndedEntries(payload, eventTime, eventTimeOK, sequence)
+		return magicShareEndedEntries(payload, eventTime, eventTimeOK, sequence, group)
 	default:
-		return []meetingTimelineEntry{newTimelineEntry(eventTime, eventTimeOK, sequence, meetingEventUserDisplayName(nil), meetingEventSummary(event), nil)}
+		return []meetingTimelineEntry{newTimelineEntry(eventTime, eventTimeOK, sequence, group, meetingEventUserDisplayName(nil), meetingEventSummary(event), nil)}
 	}
 }
 
-func participantJoinedEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int) []meetingTimelineEntry {
+func participantJoinedEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
 	items := common.GetSlice(payload, "participant_joined_items")
 	if len(items) == 0 {
-		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, "", "加入了会议", nil)}
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "加入了会议", nil)}
 	}
 	entries := make([]meetingTimelineEntry, 0, len(items))
 	for _, raw := range items {
@@ -855,15 +432,15 @@ func participantJoinedEntries(payload map[string]interface{}, fallbackTime time.
 		if subject == "" {
 			subject = "未知参会人"
 		}
-		entries = append(entries, newTimelineEntry(when, ok, sequence, subject, "加入了会议", nil))
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, "加入了会议", nil))
 	}
 	return entries
 }
 
-func participantLeftEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int) []meetingTimelineEntry {
+func participantLeftEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
 	items := common.GetSlice(payload, "participant_left_items")
 	if len(items) == 0 {
-		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, "", "离开了会议", nil)}
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "离开了会议", nil)}
 	}
 	entries := make([]meetingTimelineEntry, 0, len(items))
 	for _, raw := range items {
@@ -876,15 +453,15 @@ func participantLeftEntries(payload map[string]interface{}, fallbackTime time.Ti
 		if subject == "" {
 			subject = "未知参会人"
 		}
-		entries = append(entries, newTimelineEntry(when, ok, sequence, subject, leaveAction(item), nil))
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, leaveAction(item), nil))
 	}
 	return entries
 }
 
-func transcriptEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int) []meetingTimelineEntry {
+func transcriptEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
 	items := common.GetSlice(payload, "transcript_received_items")
 	if len(items) == 0 {
-		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, "", "产生了转写", nil)}
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "产生了转写", nil)}
 	}
 	entries := make([]meetingTimelineEntry, 0, len(items))
 	for _, raw := range items {
@@ -902,15 +479,15 @@ func transcriptEntries(payload map[string]interface{}, fallbackTime time.Time, f
 		if text != "" {
 			description = text
 		}
-		entries = append(entries, newTimelineEntry(when, ok, sequence, subject, description, nil))
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, description, nil))
 	}
 	return entries
 }
 
-func chatEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int) []meetingTimelineEntry {
+func chatEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
 	items := common.GetSlice(payload, "chat_received_items")
 	if len(items) == 0 {
-		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, "", "发送了消息", nil)}
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "发送了消息", nil)}
 	}
 	entries := make([]meetingTimelineEntry, 0, len(items))
 	for _, raw := range items {
@@ -930,15 +507,15 @@ func chatEntries(payload map[string]interface{}, fallbackTime time.Time, fallbac
 		} else {
 			description = fmt.Sprintf("[%s] %s", typeLabel, description)
 		}
-		entries = append(entries, newTimelineEntry(when, ok, sequence, subject, description, nil))
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, description, nil))
 	}
 	return entries
 }
 
-func magicShareStartedEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int) []meetingTimelineEntry {
+func magicShareStartedEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
 	items := common.GetSlice(payload, "magic_share_started_items")
 	if len(items) == 0 {
-		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, "", "开始共享内容", nil)}
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "开始共享内容", nil)}
 	}
 	entries := make([]meetingTimelineEntry, 0, len(items))
 	for _, raw := range items {
@@ -961,15 +538,15 @@ func magicShareStartedEntries(payload map[string]interface{}, fallbackTime time.
 		if url != "" {
 			details = append(details, "URL: "+url)
 		}
-		entries = append(entries, newTimelineEntry(when, ok, sequence, subject, description, details))
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, description, details))
 	}
 	return entries
 }
 
-func magicShareEndedEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int) []meetingTimelineEntry {
+func magicShareEndedEntries(payload map[string]interface{}, fallbackTime time.Time, fallbackOK bool, sequence *int, group int) []meetingTimelineEntry {
 	items := common.GetSlice(payload, "magic_share_ended_items")
 	if len(items) == 0 {
-		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, "", "结束共享", nil)}
+		return []meetingTimelineEntry{newTimelineEntry(fallbackTime, fallbackOK, sequence, group, "", "结束共享", nil)}
 	}
 	entries := make([]meetingTimelineEntry, 0, len(items))
 	for _, raw := range items {
@@ -982,16 +559,17 @@ func magicShareEndedEntries(payload map[string]interface{}, fallbackTime time.Ti
 		if subject == "" {
 			subject = "未知用户"
 		}
-		entries = append(entries, newTimelineEntry(when, ok, sequence, subject, "结束共享", nil))
+		entries = append(entries, newTimelineEntry(when, ok, sequence, group, subject, "结束共享", nil))
 	}
 	return entries
 }
 
-func newTimelineEntry(when time.Time, hasWhen bool, sequence *int, subject, description string, details []string) meetingTimelineEntry {
+func newTimelineEntry(when time.Time, hasWhen bool, sequence *int, group int, subject, description string, details []string) meetingTimelineEntry {
 	entry := meetingTimelineEntry{
 		when:        when,
 		hasWhen:     hasWhen,
 		sequence:    *sequence,
+		group:       group,
 		subject:     subject,
 		description: description,
 		details:     details,
@@ -1135,9 +713,9 @@ func needsColon(description string) bool {
 
 func leaveAction(item map[string]interface{}) string {
 	switch int(common.GetFloat(item, "leave_reason")) {
-	case leaveReasonMeetingEnded:
+	case 2:
 		return "因会议结束离开了会议"
-	case leaveReasonKicked:
+	case 3:
 		return "被移出了会议"
 	default:
 		return "离开了会议"

shortcuts/vc/vc_meeting_events_test.go

@@ -5,7 +5,6 @@ package vc
 
 import (
 	"context"
-	"encoding/json"
 	"errors"
 	"reflect"
 	"strings"
@@ -55,33 +54,6 @@ func meetingEventsStub(events []interface{}, hasMore bool, pageToken string) *ht
 	}
 }
 
-func botInfoStub() *httpmock.Stub {
-	return &httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/bot/v3/info",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"bot": map[string]interface{}{
-				"open_id":  "bot_001",
-				"app_name": "Demo Bot",
-			},
-		},
-	}
-}
-
-func botInfoErrorStub() *httpmock.Stub {
-	return &httpmock.Stub{
-		Method: "GET",
-		URL:    "/open-apis/bot/v3/info",
-		Status: 500,
-		Body: map[string]interface{}{
-			"code": 99991663,
-			"msg":  "bot info unavailable",
-		},
-	}
-}
-
 func participantJoinedEvent() map[string]interface{} {
 	return map[string]interface{}{
 		"event_id":   "event-1",
@@ -101,8 +73,6 @@ func participantJoinedEvent() map[string]interface{} {
 					"participant": map[string]interface{}{
 						"id":        "bot_001",
 						"user_name": "Demo Bot",
-						"user_type": 2,
-						"user_role": 4,
 					},
 					"join_time": "2026-04-17T08:00:00Z",
 				},
@@ -120,36 +90,6 @@ func participantJoinedEventOngoing() map[string]interface{} {
 	return event
 }
 
-func participantLeftEventWithReason(leaveReason int) map[string]interface{} {
-	return map[string]interface{}{
-		"event_id":   "event-left",
-		"event_type": "participant_left",
-		"event_time": "2026-04-17T07:18:50Z",
-		"payload": map[string]interface{}{
-			"activity_event_type": "participant_left",
-			"meeting": map[string]interface{}{
-				"id":         "7628568141510692381",
-				"topic":      "项目例会",
-				"meeting_no": "724939760",
-				"start_time": "1776410100",
-				"end_time":   "1776410100",
-			},
-			"participant_left_items": []interface{}{
-				map[string]interface{}{
-					"participant": map[string]interface{}{
-						"id":        "bot_001",
-						"user_name": "Demo Bot",
-						"user_type": 2,
-						"user_role": 4,
-					},
-					"leave_time":   "1776410330000",
-					"leave_reason": leaveReason,
-				},
-			},
-		},
-	}
-}
-
 func chatReceivedEvent() map[string]interface{} {
 	return map[string]interface{}{
 		"event_id":   "event-2",
@@ -172,7 +112,7 @@ func chatReceivedEvent() map[string]interface{} {
 			"chat_received_items": []interface{}{
 				map[string]interface{}{
 					"content":      "hello",
-					"message_type": 1,
+					"message_type": 3,
 					"operator": map[string]interface{}{
 						"id":        "u1",
 						"user_name": "Alice",
@@ -200,7 +140,7 @@ func multiChatReceivedEvent() map[string]interface{} {
 			"chat_received_items": []interface{}{
 				map[string]interface{}{
 					"content":      "第一条\n第二行",
-					"message_type": 1,
+					"message_type": 3,
 					"send_time":    "1776408061000",
 					"operator": map[string]interface{}{
 						"id":        "u1",
@@ -209,44 +149,6 @@ func multiChatReceivedEvent() map[string]interface{} {
 				},
 				map[string]interface{}{
 					"content":      "第二条",
-					"message_type": 1,
-					"send_time":    "1776408062000",
-					"operator": map[string]interface{}{
-						"id":        "u1",
-						"user_name": "Alice",
-					},
-				},
-			},
-		},
-	}
-}
-
-func mixedChatAndReactionEvent() map[string]interface{} {
-	return map[string]interface{}{
-		"event_id":   "event-reaction",
-		"event_type": "chat_received",
-		"event_time": "2026-04-17T08:05:00Z",
-		"payload": map[string]interface{}{
-			"activity_event_type": "chat_received",
-			"meeting": map[string]interface{}{
-				"id":         "7628568141510692381",
-				"topic":      "项目例会",
-				"meeting_no": "724939760",
-				"start_time": "1776407700",
-				"end_time":   "1776411300",
-			},
-			"chat_received_items": []interface{}{
-				map[string]interface{}{
-					"content":      "hello",
-					"message_type": 1,
-					"send_time":    "1776408061000",
-					"operator": map[string]interface{}{
-						"id":        "u1",
-						"user_name": "Alice",
-					},
-				},
-				map[string]interface{}{
-					"content":      "OK",
 					"message_type": 3,
 					"send_time":    "1776408062000",
 					"operator": map[string]interface{}{
@@ -512,7 +414,7 @@ func TestMeetingEvents_DryRun(t *testing.T) {
 		"--start", "1710000000",
 		"--end", "1710003600",
 		"--dry-run",
-		"--as", "bot",
+		"--as", "user",
 	}, f, stdout)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -540,7 +442,7 @@ func TestMeetingEvents_DryRun_PageAllUsesMaxLimit(t *testing.T) {
 		"--meeting-id", "7628568141510692381",
 		"--page-all",
 		"--dry-run",
-		"--as", "bot",
+		"--as", "user",
 	}, f, stdout)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -555,39 +457,24 @@ func TestMeetingEvents_ExecuteJSON_PageAll(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, true, "pt_2"))
 	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, false, ""))
-	reg.Register(botInfoStub())
 
 	err := mountAndRun(t, VCMeetingEvents, []string{
 		"+meeting-events",
 		"--meeting-id", "7628568141510692381",
 		"--format", "json",
 		"--page-all",
-		"--as", "bot",
+		"--as", "user",
 	}, f, stdout)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
 	reg.Verify(t)
 
-	var envelope map[string]interface{}
-	if err := json.Unmarshal([]byte(stdout.String()), &envelope); err != nil {
-		t.Fatalf("unmarshal stdout: %v: %s", err, stdout.String())
-	}
-	events := common.GetSlice(common.GetMap(envelope, "data"), "events")
-	if got := len(events); got != 2 {
-		t.Fatalf("events len = %d, want 2: %s", got, stdout.String())
-	}
-	for _, raw := range events {
-		event, _ := raw.(map[string]interface{})
-		if _, ok := event["summary"]; ok {
-			t.Fatalf("event should not expose summary: %s", stdout.String())
-		}
-		if _, ok := event["raw"]; ok {
-			t.Fatalf("event should not expose raw: %s", stdout.String())
-		}
-	}
 	out := strings.ReplaceAll(stdout.String(), " ", "")
 	out = strings.ReplaceAll(out, "\n", "")
+	if count := strings.Count(out, `"event_type":"participant_joined"`); count != 2 {
+		t.Fatalf("expected 2 aggregated events, got %d: %s", count, stdout.String())
+	}
 	if !strings.Contains(out, `"has_more":false`) {
 		t.Fatalf("expected final has_more=false: %s", stdout.String())
 	}
@@ -596,80 +483,6 @@ func TestMeetingEvents_ExecuteJSON_PageAll(t *testing.T) {
 func TestMeetingEvents_ExecuteJSON(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, true, "1710000000000000000"))
-	reg.Register(botInfoStub())
-
-	err := mountAndRun(t, VCMeetingEvents, []string{
-		"+meeting-events",
-		"--meeting-id", "7628568141510692381",
-		"--format", "json",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	reg.Verify(t)
-
-	out := strings.ReplaceAll(stdout.String(), " ", "")
-	out = strings.ReplaceAll(out, "\n", "")
-	for _, want := range []string{
-		`"identity":{"id":"bot_001","name":"DemoBot","participant_type":"bot","label":"DemoBot[bot]"}`,
-		`"role":"bot"`,
-		`"event_type":"participant_joined"`,
-		`"actors":[`,
-		`"start_time":"2026-04-17T06:35:00Z"`,
-		`"has_more":true`,
-		`"page_token":"1710000000000000000"`,
-		`"events":[`,
-	} {
-		if !strings.Contains(out, want) {
-			t.Fatalf("json output missing %q: %s", want, stdout.String())
-		}
-	}
-	for _, unwanted := range []string{
-		`"current_participants":`,
-		`"is_self":`,
-		`"summary":`,
-		`"raw":`,
-	} {
-		if strings.Contains(out, unwanted) {
-			t.Fatalf("json output should not contain %q: %s", unwanted, stdout.String())
-		}
-	}
-}
-
-func TestMeetingEvents_ExecuteJSON_BotIdentityErrorDoesNotBlockEvents(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, false, ""))
-	reg.Register(botInfoErrorStub())
-
-	err := mountAndRun(t, VCMeetingEvents, []string{
-		"+meeting-events",
-		"--meeting-id", "7628568141510692381",
-		"--format", "json",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	reg.Verify(t)
-
-	out := strings.ReplaceAll(stdout.String(), " ", "")
-	out = strings.ReplaceAll(out, "\n", "")
-	for _, want := range []string{
-		`"event_type":"participant_joined"`,
-		`"identity":{"participant_type":"bot","label":"bot"}`,
-		`"warnings":[`,
-		`identityunavailable`,
-	} {
-		if !strings.Contains(out, want) {
-			t.Fatalf("json output missing %q: %s", want, stdout.String())
-		}
-	}
-}
-
-func TestMeetingEvents_ExecuteJSON_UserIdentitySkipsBotInfo(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, false, ""))
 
 	err := mountAndRun(t, VCMeetingEvents, []string{
 		"+meeting-events",
@@ -685,205 +498,26 @@ func TestMeetingEvents_ExecuteJSON_UserIdentitySkipsBotInfo(t *testing.T) {
 	out := strings.ReplaceAll(stdout.String(), " ", "")
 	out = strings.ReplaceAll(out, "\n", "")
 	for _, want := range []string{
-		`"identity":{"id":"ou_testuser","participant_type":"human","label":"ou_testuser[human]"}`,
 		`"event_type":"participant_joined"`,
-		`"has_more":false`,
-	} {
-		if !strings.Contains(out, want) {
-			t.Fatalf("user json output missing %q: %s", want, stdout.String())
-		}
-	}
-}
-
-func TestMeetingEvents_ExecuteJSON_OngoingMeetingOmitsEndTime(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	reg.Register(meetingEventsStub([]interface{}{participantJoinedEventOngoing()}, false, ""))
-	reg.Register(botInfoStub())
-
-	err := mountAndRun(t, VCMeetingEvents, []string{
-		"+meeting-events",
-		"--meeting-id", "7628568141510692381",
-		"--format", "json",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	reg.Verify(t)
-
-	var envelope map[string]interface{}
-	if err := json.Unmarshal([]byte(stdout.String()), &envelope); err != nil {
-		t.Fatalf("invalid json output: %v\n%s", err, stdout.String())
-	}
-	data := common.GetMap(envelope, "data")
-	meeting := common.GetMap(data, "meeting")
-	if got := common.GetString(meeting, "status"); got != "ongoing" {
-		t.Fatalf("meeting status = %q, want ongoing: %s", got, stdout.String())
-	}
-	if _, ok := meeting["end_time"]; ok {
-		t.Fatalf("ongoing meeting should not expose dirty top-level end_time: %s", stdout.String())
-	}
-}
-
-func TestBuildMeetingEventsOutput_MeetingEndedLeaveReasonOverridesDirtyMeetingEndTime(t *testing.T) {
-	out := buildMeetingEventsOutput(map[string]interface{}{}, []interface{}{
-		participantLeftEventWithReason(leaveReasonMeetingEnded),
-	}, meetingEventsIdentity{})
-
-	if got := out.Meeting.Status; got != "ended" {
-		t.Fatalf("meeting status = %q, want ended", got)
-	}
-	if got := out.Meeting.EndTime; got != "2026-04-17T07:18:50Z" {
-		t.Fatalf("meeting end_time = %q, want leave time", got)
-	}
-}
-
-func TestBuildMeetingEventsOutput_NormalLeaveReasonDoesNotEndMeeting(t *testing.T) {
-	out := buildMeetingEventsOutput(map[string]interface{}{}, []interface{}{
-		participantLeftEventWithReason(leaveReasonUserLeft),
-	}, meetingEventsIdentity{})
-
-	if got := out.Meeting.Status; got != "ongoing" {
-		t.Fatalf("meeting status = %q, want ongoing", got)
-	}
-	if got := out.Meeting.EndTime; got != "" {
-		t.Fatalf("meeting end_time = %q, want empty", got)
-	}
-}
-
-func TestRenderMeetingEventsPretty_MeetingEndedLeaveReasonOverridesDirtyMeetingEndTime(t *testing.T) {
-	timeline := buildMeetingEventTimeline([]interface{}{
-		participantLeftEventWithReason(leaveReasonMeetingEnded),
-	})
-	got := renderMeetingEventsPretty(timeline)
-
-	if strings.Contains(got, "进行中") {
-		t.Fatalf("pretty output should not show ongoing for meeting-ended leave reason: %s", got)
-	}
-	if !strings.Contains(got, "会议时间：2026-04-17 15:15:00 - 2026-04-17 15:18:50") {
-		t.Fatalf("pretty output missing derived meeting end window: %s", got)
-	}
-}
-
-func TestBuildMeetingEventsOutput_UsesLatestMeetingSnapshot(t *testing.T) {
-	out := buildMeetingEventsOutput(map[string]interface{}{}, []interface{}{
-		participantJoinedEventOngoing(),
-		participantJoinedEvent(),
-	}, meetingEventsIdentity{})
-
-	if got := out.Meeting.Status; got != "ended" {
-		t.Fatalf("meeting status = %q, want ended", got)
-	}
-	if got := out.Meeting.EndTime; got != "2026-04-17T07:35:00Z" {
-		t.Fatalf("meeting end_time = %q, want latest ended snapshot", got)
-	}
-	if got := len(out.Events); got != 2 {
-		t.Fatalf("events len = %d, want 2", got)
-	}
-}
-
-func TestBuildMeetingEventsOutput_EmptyEventsHasUnknownMeetingStatus(t *testing.T) {
-	out := buildMeetingEventsOutput(map[string]interface{}{}, nil, meetingEventsIdentity{})
-
-	if got := out.Meeting.Status; got != "unknown" {
-		t.Fatalf("meeting status = %q, want unknown", got)
-	}
-}
-
-func TestMeetingEventsMeetingFromPayload_StartOnlyIsOngoing(t *testing.T) {
-	got := meetingEventsMeetingFromPayload(map[string]interface{}{
-		"id":         "m1",
-		"start_time": "1776410100",
-	})
-
-	if got.Status != "ongoing" {
-		t.Fatalf("meeting status = %q, want ongoing", got.Status)
-	}
-	if got.StartTime != "2026-04-17T07:15:00Z" {
-		t.Fatalf("meeting start_time = %q, want normalized RFC3339", got.StartTime)
-	}
-	if got.EndTime != "" {
-		t.Fatalf("meeting end_time = %q, want empty", got.EndTime)
-	}
-}
-
-func TestMeetingEvents_ExecuteNDJSONIncludesMetadataRow(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, true, "1710000000000000000"))
-	reg.Register(botInfoStub())
-
-	err := mountAndRun(t, VCMeetingEvents, []string{
-		"+meeting-events",
-		"--meeting-id", "7628568141510692381",
-		"--format", "ndjson",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	reg.Verify(t)
-
-	lines := strings.Split(strings.TrimSpace(stdout.String()), "\n")
-	if len(lines) != 2 {
-		t.Fatalf("ndjson lines = %d, want 2: %s", len(lines), stdout.String())
-	}
-	if !strings.Contains(lines[0], `"row_type":"event"`) || !strings.Contains(lines[0], `"event_type":"participant_joined"`) {
-		t.Fatalf("first ndjson row should be event: %s", lines[0])
-	}
-	for _, unwanted := range []string{
-		`"summary":`,
-		`"raw":`,
-	} {
-		if strings.Contains(lines[0], unwanted) {
-			t.Fatalf("event ndjson row should not contain %q: %s", unwanted, lines[0])
-		}
-	}
-	for _, want := range []string{
-		`"row_type":"metadata"`,
 		`"has_more":true`,
 		`"page_token":"1710000000000000000"`,
-		`"identity":`,
+		`"events":[`,
 	} {
-		if !strings.Contains(lines[1], want) {
-			t.Fatalf("metadata ndjson row missing %q: %s", want, lines[1])
+		if !strings.Contains(out, want) {
+			t.Fatalf("json output missing %q: %s", want, stdout.String())
 		}
 	}
 }
 
-func TestMeetingEventsEventRows_OmitsEmptyEventFields(t *testing.T) {
-	rows := meetingEventsEventRows([]meetingEventsEvent{
-		{EventType: "unknown_event"},
-	}, nil)
-	if len(rows) != 1 {
-		t.Fatalf("rows len = %d, want 1", len(rows))
-	}
-	row, ok := rows[0].(map[string]interface{})
-	if !ok {
-		t.Fatalf("row type = %T, want map", rows[0])
-	}
-	for _, unwanted := range []string{"event_id", "event_time", "actors", "payload"} {
-		if _, exists := row[unwanted]; exists {
-			t.Fatalf("row should omit %q when empty: %#v", unwanted, row)
-		}
-	}
-	if got := row["row_type"]; got != "event" {
-		t.Fatalf("row_type = %v, want event", got)
-	}
-	if got := row["event_type"]; got != "unknown_event" {
-		t.Fatalf("event_type = %v, want unknown_event", got)
-	}
-}
-
 func TestMeetingEvents_ExecuteJSON_PrunesEmptySlices(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	reg.Register(meetingEventsStub([]interface{}{chatReceivedEvent()}, false, ""))
-	reg.Register(botInfoStub())
 
 	err := mountAndRun(t, VCMeetingEvents, []string{
 		"+meeting-events",
 		"--meeting-id", "7628568141510692381",
 		"--format", "json",
-		"--as", "bot",
+		"--as", "user",
 	}, f, stdout)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -902,54 +536,20 @@ func TestMeetingEvents_ExecuteJSON_PrunesEmptySlices(t *testing.T) {
 			t.Fatalf("json output should not contain %q: %s", unwanted, out)
 		}
 	}
-	if !strings.Contains(out, `"message_type": 1`) {
+	if !strings.Contains(out, `"message_type": 3`) {
 		t.Fatalf("json output should keep numeric fields: %s", out)
 	}
 }
 
-func TestMeetingEvents_ExecuteJSON_PreservesReactionItems(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	reg.Register(meetingEventsStub([]interface{}{mixedChatAndReactionEvent()}, false, ""))
-	reg.Register(botInfoStub())
-
-	err := mountAndRun(t, VCMeetingEvents, []string{
-		"+meeting-events",
-		"--meeting-id", "7628568141510692381",
-		"--format", "json",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	reg.Verify(t)
-
-	out := strings.ReplaceAll(stdout.String(), " ", "")
-	out = strings.ReplaceAll(out, "\n", "")
-	for _, want := range []string{
-		`"event_type":"chat_received"`,
-		`"chat_received_items":[`,
-		`"content":"OK"`,
-		`"message_type":3`,
-	} {
-		if !strings.Contains(out, want) {
-			t.Fatalf("json output missing %q: %s", want, stdout.String())
-		}
-	}
-	if strings.Contains(out, `"im_post"`) {
-		t.Fatalf("json output should not include IM post payload: %s", stdout.String())
-	}
-}
-
 func TestMeetingEvents_ExecutePretty(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	reg.Register(meetingEventsStub([]interface{}{participantJoinedEventOngoing(), multiChatReceivedEvent(), magicShareStartedEvent()}, true, "1710000000000000000"))
-	reg.Register(botInfoStub())
 
 	err := mountAndRun(t, VCMeetingEvents, []string{
 		"+meeting-events",
 		"--meeting-id", "7628568141510692381",
 		"--format", "pretty",
-		"--as", "bot",
+		"--as", "user",
 	}, f, stdout)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -958,12 +558,11 @@ func TestMeetingEvents_ExecutePretty(t *testing.T) {
 
 	out := stdout.String()
 	for _, want := range []string{
-		"当前身份：Demo Bot [bot]",
 		"会议主题：项目例会",
 		"会议时间：2026-04-17 15:15:00（进行中）",
 		"Demo Bot(bot_001) 加入了会议",
-		"Alice(u1): [text] 第一条\\n第二行",
-		"Alice(u1): [text] 第二条",
+		"Alice(u1): [reaction] 第一条\\n第二行",
+		"Alice(u1): [reaction] 第二条",
 		"Bob(u2) 开始共享「共享文档」",
 		"URL: https://example.com/doc",
 		"page_token: 1710000000000000000",
@@ -983,13 +582,12 @@ func TestMeetingEvents_ExecutePretty(t *testing.T) {
 func TestMeetingEvents_ExecutePretty_PrintsPageTokenWithoutHasMore(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	reg.Register(meetingEventsStub([]interface{}{participantJoinedEventOngoing()}, false, "pt_last"))
-	reg.Register(botInfoStub())
 
 	err := mountAndRun(t, VCMeetingEvents, []string{
 		"+meeting-events",
 		"--meeting-id", "7628568141510692381",
 		"--format", "pretty",
-		"--as", "bot",
+		"--as", "user",
 	}, f, stdout)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -1008,13 +606,12 @@ func TestMeetingEvents_ExecutePretty_PrintsPageTokenWithoutHasMore(t *testing.T)
 func TestMeetingEvents_ExecuteEmpty(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	reg.Register(meetingEventsStub(nil, false, ""))
-	reg.Register(botInfoStub())
 
 	err := mountAndRun(t, VCMeetingEvents, []string{
 		"+meeting-events",
 		"--meeting-id", "7628568141510692381",
 		"--format", "pretty",
-		"--as", "bot",
+		"--as", "user",
 	}, f, stdout)
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -1253,9 +850,9 @@ func TestLeaveAction(t *testing.T) {
 		item map[string]interface{}
 		want string
 	}{
-		{name: "meeting ended", item: map[string]interface{}{"leave_reason": leaveReasonMeetingEnded}, want: "因会议结束离开了会议"},
-		{name: "kicked", item: map[string]interface{}{"leave_reason": leaveReasonKicked}, want: "被移出了会议"},
-		{name: "default", item: map[string]interface{}{"leave_reason": leaveReasonUserLeft}, want: "离开了会议"},
+		{name: "meeting ended", item: map[string]interface{}{"leave_reason": 2}, want: "因会议结束离开了会议"},
+		{name: "kicked", item: map[string]interface{}{"leave_reason": 3}, want: "被移出了会议"},
+		{name: "default", item: map[string]interface{}{"leave_reason": 1}, want: "离开了会议"},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -1287,70 +884,6 @@ func TestMeetingEventUserWithID(t *testing.T) {
 	}
 }
 
-func TestMeetingEventsIdentityFromParticipant_UsesContractFields(t *testing.T) {
-	got := meetingEventsIdentityFromParticipant(map[string]interface{}{
-		"id":        "u1",
-		"user_name": "Alice",
-		"user_type": 1,
-		"user_role": 2,
-	}, meetingEventsIdentity{})
-
-	if got.ParticipantType != "human" || got.Role != "host" {
-		t.Fatalf("identity = %#v, want participant_type=human role=host", got)
-	}
-}
-
-func TestMeetingEventsIdentityFromParticipant_UserRoleParticipant(t *testing.T) {
-	got := meetingEventsIdentityFromParticipant(map[string]interface{}{
-		"id":        "u1",
-		"user_name": "Alice",
-		"user_type": 1,
-		"user_role": 1,
-	}, meetingEventsIdentity{})
-
-	if got.Role != "participant" {
-		t.Fatalf("identity = %#v, want role=participant", got)
-	}
-}
-
-func TestMeetingEventsIdentityFromParticipant_UserTypeApp(t *testing.T) {
-	got := meetingEventsIdentityFromParticipant(map[string]interface{}{
-		"id":        "ou_app",
-		"user_name": "Demo Bot",
-		"user_type": 10,
-		"user_role": 1,
-	}, meetingEventsIdentity{})
-
-	if got.ParticipantType != "bot" {
-		t.Fatalf("identity = %#v, want participant_type=bot", got)
-	}
-}
-
-func TestMeetingEventsIdentityFromParticipant_UnknownUserType(t *testing.T) {
-	got := meetingEventsIdentityFromParticipant(map[string]interface{}{
-		"id":        "u_unknown",
-		"user_name": "Unknown",
-		"user_type": 0,
-		"user_role": 1,
-	}, meetingEventsIdentity{})
-
-	if got.ParticipantType != "unknown" {
-		t.Fatalf("identity = %#v, want participant_type=unknown", got)
-	}
-}
-
-func TestMeetingEventsIdentityFromParticipant_IgnoresGenericTypeField(t *testing.T) {
-	got := meetingEventsIdentityFromParticipant(map[string]interface{}{
-		"id":        "u1",
-		"user_name": "Alice",
-		"type":      "bot",
-	}, meetingEventsIdentity{})
-
-	if got.ParticipantType != "human" {
-		t.Fatalf("identity = %#v, generic type field should not drive participant_type", got)
-	}
-}
-
 func TestMeetingEventSummary(t *testing.T) {
 	tests := []struct {
 		name  string
@@ -1400,22 +933,6 @@ func TestMeetingEventSummary(t *testing.T) {
 	}
 }
 
-func TestMeetingEventsEventFromPayloadUsesActivityEventTypeFallback(t *testing.T) {
-	event := participantJoinedEvent()
-	delete(event, "event_type")
-
-	got := meetingEventsEventFromPayload(event, meetingEventsIdentity{})
-	if got.EventType != "participant_joined" {
-		t.Fatalf("EventType = %q, want participant_joined", got.EventType)
-	}
-	if len(got.Actors) != 1 {
-		t.Fatalf("actors len = %d, want 1: %#v", len(got.Actors), got.Actors)
-	}
-	if got.Actors[0].ID != "bot_001" {
-		t.Fatalf("actor id = %q, want bot_001", got.Actors[0].ID)
-	}
-}
-
 func TestEscapePrettyText(t *testing.T) {
 	got := escapePrettyText("line1\nline2\t\r" + string(rune(0x07)))
 	want := `line1\nline2\t\r\u0007`

shortcuts/wiki/wiki_list_copy_test.go

@@ -199,19 +199,6 @@ func TestWikiNodeListNormalizesWikiURLParentNodeToken(t *testing.T) {
 	}
 }
 
-func TestWikiNodeListAcceptsOpaqueParentNodeToken(t *testing.T) {
-	t.Parallel()
-
-	const opaqueNodeToken = "Q6ZM_EXAMPLE_TOKEN"
-	token, err := normalizeWikiNodeListParentToken(opaqueNodeToken)
-	if err != nil {
-		t.Fatalf("normalizeWikiNodeListParentToken() error = %v", err)
-	}
-	if token != opaqueNodeToken {
-		t.Fatalf("token = %q, want %q", token, opaqueNodeToken)
-	}
-}
-
 func TestWikiNodeListRejectsAmbiguousSpaceAndParentTokens(t *testing.T) {
 	t.Parallel()
 
@@ -237,6 +224,11 @@ func TestWikiNodeListRejectsAmbiguousSpaceAndParentTokens(t *testing.T) {
 			input:   "wik_placeholder/child",
 			wantMsg: "raw wiki node token",
 		},
+		{
+			name:    "document token",
+			input:   "docx_placeholder_parent",
+			wantMsg: "must be a wiki node token",
+		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -359,11 +351,10 @@ func TestWikiNodeListPassesParentNodeToken(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 
 	factory, stdout, _, reg := cmdutil.TestFactory(t, wikiTestConfig())
-	const parentNodeToken = "Q6ZM_EXAMPLE_TOKEN"
 
 	stub := &httpmock.Stub{
 		Method: "GET",
-		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/nodes?page_size=50&parent_node_token=" + parentNodeToken,
+		URL:    "/open-apis/wiki/v2/spaces/7211568716812369922/nodes?page_size=50&parent_node_token=wik_parent",
 		Body: map[string]interface{}{
 			"code": 0,
 			"data": map[string]interface{}{
@@ -374,7 +365,7 @@ func TestWikiNodeListPassesParentNodeToken(t *testing.T) {
 						"node_token":        "wik_child",
 						"obj_token":         "docx_child",
 						"obj_type":          "docx",
-						"parent_node_token": parentNodeToken,
+						"parent_node_token": "wik_parent",
 						"node_type":         "origin",
 						"title":             "Child Doc",
 						"has_child":         false,
@@ -387,7 +378,7 @@ func TestWikiNodeListPassesParentNodeToken(t *testing.T) {
 	reg.Register(stub)
 
 	err := mountAndRunWiki(t, WikiNodeList, []string{
-		"+node-list", "--space-id", "7211568716812369922", "--parent-node-token", parentNodeToken, "--as", "bot",
+		"+node-list", "--space-id", "7211568716812369922", "--parent-node-token", "wik_parent", "--as", "bot",
 	}, factory, stdout)
 	if err != nil {
 		t.Fatalf("mountAndRunWiki() error = %v", err)
@@ -409,8 +400,8 @@ func TestWikiNodeListPassesParentNodeToken(t *testing.T) {
 	if len(envelope.Data.Nodes) != 1 {
 		t.Fatalf("len(nodes) = %d, want 1", len(envelope.Data.Nodes))
 	}
-	if envelope.Data.Nodes[0]["parent_node_token"] != parentNodeToken {
-		t.Fatalf("nodes[0].parent_node_token = %v, want %q", envelope.Data.Nodes[0]["parent_node_token"], parentNodeToken)
+	if envelope.Data.Nodes[0]["parent_node_token"] != "wik_parent" {
+		t.Fatalf("nodes[0].parent_node_token = %v, want %q", envelope.Data.Nodes[0]["parent_node_token"], "wik_parent")
 	}
 }
 

shortcuts/wiki/wiki_node_get.go

@@ -69,8 +69,8 @@ var WikiNodeGet = common.Shortcut{
 		{Name: "space-id", Desc: "optional: assert the resolved node lives in this space"},
 	},
 	Tips: []string{
-		"--node-token accepts a raw wiki node_token, obj_token, or a Lark URL like https://feishu.cn/wiki/<token> or https://feishu.cn/docx/<token>.",
-		"For raw obj_tokens, pass --obj-type so the API knows how to resolve them; URL inputs infer it from the path.",
+		"--node-token accepts a raw token (wikcnXXX, docxXXX, ...) or a Lark URL like https://feishu.cn/wiki/<token> or https://feishu.cn/docx/<token>.",
+		"For raw obj_tokens (not starting with wik), pass --obj-type so the API knows how to resolve them; URL inputs infer it from the path.",
 		"Pair with +move / +node-copy / +delete-space to confirm space_id, obj_type, and parent before mutating.",
 		"--token is the deprecated original name and still works for backward compatibility; new scripts should use --node-token.",
 	},
@@ -235,10 +235,29 @@ func parseWikiNodeGetSpec(rawToken, rawObjType, rawSpaceID string) (wikiNodeGetS
 		).WithParam("--node-token")
 	} else {
 		spec.Token = tokenInput
-		if spec.ObjType == "" {
+		if looksLikeWikiNodeToken(spec.Token) {
 			spec.SourceKind = "raw-node"
+			// node_tokens take no obj_type; reject a conflicting flag rather
+			// than silently passing it (the API would just ignore it, but the
+			// mismatch signals caller confusion).
+			if spec.ObjType != "" {
+				return wikiNodeGetSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
+					"--obj-type is only valid for obj_tokens; %q looks like a node_token",
+					spec.Token,
+				).WithParam("--obj-type")
+			}
 		} else {
 			spec.SourceKind = "raw-obj"
+			// A raw obj_token needs an explicit obj_type: get_node would
+			// otherwise default to "doc" and fail confusingly for docx /
+			// sheet / bitable / ... Fail fast with the same upfront contract
+			// as +node-delete instead of deferring to an opaque API error.
+			if spec.ObjType == "" {
+				return wikiNodeGetSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
+					"--obj-type is required for a raw obj_token %q (one of: %s); or pass a typed Lark URL (e.g. /docx/<token>) so it can be inferred",
+					spec.Token, strings.Join(wikiNodeGetObjTypeEnum, ", "),
+				).WithParam("--obj-type")
+			}
 		}
 	}
 
@@ -251,6 +270,18 @@ func parseWikiNodeGetSpec(rawToken, rawObjType, rawSpaceID string) (wikiNodeGetS
 	return spec, nil
 }
 
+// looksLikeWikiNodeToken returns true when the token has the `wik` prefix used
+// for node_tokens. Lark wiki tokens are case-insensitive in practice; callers
+// pass `wikcn`/`wikus`/`Wik...` interchangeably, so normalize for the check.
+//
+// This is a heuristic based on the current Lark token-naming convention, not a
+// guaranteed invariant: if Lark ever introduces a non-node token type that
+// also starts with `wik`, it would be misclassified. Worst case is a
+// confusing API error (no data risk); revisit if the token scheme changes.
+func looksLikeWikiNodeToken(token string) bool {
+	return strings.HasPrefix(strings.ToLower(token), "wik")
+}
+
 // tokenAndObjTypeFromWikiURL extracts the token and inferred obj_type from a
 // Lark URL path. The wiki path returns an empty obj_type because node_tokens
 // don't need one.

shortcuts/wiki/wiki_node_get_test.go

@@ -31,22 +31,6 @@ func TestParseWikiNodeGetSpecRawNodeToken(t *testing.T) {
 	}
 }
 
-func TestParseWikiNodeGetSpecOpaqueRawNodeToken(t *testing.T) {
-	t.Parallel()
-
-	const opaqueNodeToken = "Sm78_EXAMPLE_TOKEN"
-	spec, err := parseWikiNodeGetSpec(opaqueNodeToken, "", "")
-	if err != nil {
-		t.Fatalf("parseWikiNodeGetSpec() error = %v", err)
-	}
-	if spec.Token != opaqueNodeToken || spec.ObjType != "" || spec.SourceKind != "raw-node" {
-		t.Fatalf("spec = %+v, want raw-node %s with no obj_type", spec, opaqueNodeToken)
-	}
-	if got := spec.RequestParams(); !reflect.DeepEqual(got, map[string]interface{}{"token": opaqueNodeToken}) {
-		t.Fatalf("RequestParams() = %v, want {token: %s}", got, opaqueNodeToken)
-	}
-}
-
 func TestParseWikiNodeGetSpecRawObjTokenWithExplicitObjType(t *testing.T) {
 	t.Parallel()
 
@@ -59,30 +43,23 @@ func TestParseWikiNodeGetSpecRawObjTokenWithExplicitObjType(t *testing.T) {
 	}
 }
 
-func TestParseWikiNodeGetSpecRawTokenWithoutObjTypeDefaultsToNodeToken(t *testing.T) {
+func TestParseWikiNodeGetSpecRejectsRawObjTokenWithoutObjType(t *testing.T) {
 	t.Parallel()
 
-	spec, err := parseWikiNodeGetSpec("bascnXYZ", "", "")
-	if err != nil {
-		t.Fatalf("parseWikiNodeGetSpec() error = %v", err)
-	}
-	if spec.Token != "bascnXYZ" || spec.ObjType != "" || spec.SourceKind != "raw-node" {
-		t.Fatalf("spec = %+v, want raw-node bascnXYZ with no obj_type", spec)
+	// Mirrors +node-delete: a raw obj_token with no --obj-type must fail
+	// upfront instead of defaulting to "doc" and hitting an opaque API error.
+	_, err := parseWikiNodeGetSpec("bascnXYZ", "", "")
+	if err == nil || !strings.Contains(err.Error(), "--obj-type is required for a raw obj_token") {
+		t.Fatalf("expected raw obj_token obj-type-required error, got %v", err)
 	}
 }
 
-func TestParseWikiNodeGetSpecRawTokenWithObjTypeUsesObjTokenLookup(t *testing.T) {
+func TestParseWikiNodeGetSpecRejectsObjTypeOnNodeToken(t *testing.T) {
 	t.Parallel()
 
-	spec, err := parseWikiNodeGetSpec("wikcnABC", "docx", "")
-	if err != nil {
-		t.Fatalf("parseWikiNodeGetSpec() error = %v", err)
-	}
-	if spec.Token != "wikcnABC" || spec.ObjType != "docx" || spec.SourceKind != "raw-obj" {
-		t.Fatalf("spec = %+v, want raw-obj wikcnABC with obj_type docx", spec)
-	}
-	if got := spec.RequestParams(); !reflect.DeepEqual(got, map[string]interface{}{"token": "wikcnABC", "obj_type": "docx"}) {
-		t.Fatalf("RequestParams() = %v, want {token: wikcnABC, obj_type: docx}", got)
+	_, err := parseWikiNodeGetSpec("wikcnABC", "docx", "")
+	if err == nil || !strings.Contains(err.Error(), "only valid for obj_tokens") {
+		t.Fatalf("expected node_token + obj_type rejection, got %v", err)
 	}
 }
 

shortcuts/wiki/wiki_node_list.go

@@ -207,6 +207,11 @@ func normalizeWikiNodeListParentToken(parentNodeToken string) (string, error) {
 			"--parent-node-token must be a raw wiki node token, not a partial URL or path",
 		).WithParam("--parent-node-token")
 	}
+	if !looksLikeWikiNodeToken(parentNodeToken) {
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"--parent-node-token must be a wiki node token; do not pass a docx/sheet/base/file token",
+		).WithParam("--parent-node-token").WithHint("Run `lark-cli wiki +node-get --node-token <url-or-token>` to resolve a document URL or obj_token to the wiki `node_token` first.")
+	}
 	if err := validateOptionalResourceName(parentNodeToken, "--parent-node-token"); err != nil {
 		return "", err
 	}

skills/lark-apps/SKILL.md

@@ -12,16 +12,6 @@ metadata:
 
 妙搭应用属于用户资产。默认用 `--as user`；认证、scope、exit-10、高风险确认、`_notice` 等通用处理只读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，不要在本 skill 里复制。妙搭应用有三条开发路径：**本地全栈**（拉源码本地写）/ **HTML 托管**（发布静态产物）/ **云端会话**（妙搭 AI 生成）。
 
-## 身份与一次性授权
-
-妙搭应用是用户的个人资产，统一 `--as user`（见开头）。**首次操作前先一次性把本域 scope 全拿到**，避免每条命令首次跑都触发新一轮授权，或未授权直接打到 openapi 导致服务端报错：
-
-```bash
-lark-cli auth login --domain apps
-```
-
-因缺权限失败（`error.subtype == "missing_scope"`）时的通用处理见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，同样按 `--domain apps` 授权。
-
 ## 意图路由
 
 按具体操作查命令（开发路径先用下方「选择开发路径」判定表定好再进来取命令）：

skills/lark-apps/references/lark-apps-db-execute.md

@@ -11,7 +11,7 @@
 - 必填：`--app-id`，以及 `--sql` / `--file` 二选一（互斥）。
 - `--sql`：内联 SQL 文本；传 `-` 时从 stdin 读。绝对路径文件经 stdin 传入：`--sql - < <absolute-path>`（shell 解析路径，CLI 仅接收内容）。
 - `--file`：`.sql` 文件路径，需为工作目录内的相对路径（如 `--file ./migration.sql`）；绝对路径、或经 `..`/符号链接越出工作目录的路径会被拒绝。文件不在工作目录内时，改用 `--sql - < <文件路径>` 经 stdin 传入。
-- `--environment` 枚举：`dev` / `online`，**不传则由服务端按应用是否开启多环境自动选择（多环境→`dev`，未开启多环境→`online`）**；要固定环境就显式传 `--environment dev|online`。**未开启多环境的应用显式传 `--environment dev` 会报错（无 dev 分支）——这类应用不传 `--environment`（走 `online`）或显式 `--environment online`**。旧名 `--env` 已**移除**：传入会报 validation 错（提示改用 `--environment`），一律用 `--environment`。
+- `--environment` 枚举：`dev` / `online`，**默认 `dev`**；操作线上库、或**未开启多环境的应用（其数据库在 `online`，没有 dev 分支）**时显式 `--environment online`。旧名 `--env` 已**移除**：传入会报 validation 错（提示改用 `--environment`），一律用 `--environment`。
 - risk 是 `high-risk-write`（SQL 可含 DML/DDL）：任何执行都需 `--yes`，否则返回 `confirmation_required` / exit 10。`--dry-run` 预览不需要 `--yes`。
 - **不会自动为你包事务，事务边界需自己在 SQL 里控制**：多语句默认逐条独立提交，中间某条失败时前序语句已生效、不会回滚；若需要「要么全部成功、要么全部回滚」的原子性，请在 SQL 内显式写 `BEGIN … COMMIT`（详见下「Agent 规则」）。
 

skills/lark-apps/references/lark-apps-db.md

@@ -28,7 +28,7 @@
 
 ## 约定（先读）
 
-- **环境 `--environment dev|online`（可省略）**：看表、看结构、数据导入导出、变更追溯、审计、配额都按环境区分。省略 `--environment` 时 CLI 不带该参数、由服务端按应用形态自动选分支——多环境应用走 `dev`、未开多环境的走 `online`；要固定环境就显式传。唯一会报错的组合：对未开多环境的应用显式传 `--environment dev`（无 `dev` 分支）。写操作建议先在 `dev` 验（仅多环境应用有 `dev`）。旧名 `--env` 已**移除**：传入会报 validation 错（提示改用 `--environment`），一律用 `--environment`。`+db-env-diff`/`+db-env-migrate` 是「dev→online 发布」语义，**没有** `--environment`。
+- **环境 `--environment dev|online`（所有 db 命令统一默认 `dev`）**：看表、看结构、数据导入导出、变更追溯、审计、配额都按环境区分，写操作建议先在 `dev` 验。**注意：只有开启了多环境（`+db-env-create`）的应用才有 `dev` 分支；未开启多环境的应用其数据库在 `online`——对这类应用必须显式 `--environment online`，否则默认的 `dev` 分支不存在、会报错**。旧名 `--env` 已**移除**：传入会报 validation 错（提示改用 `--environment`），一律用 `--environment`。`+db-env-diff`/`+db-env-migrate` 是「dev→online 发布」语义、`+db-recovery-*` 作用于当前库，二者**没有** `--environment`。
 - **本地文件 / `--output` 用工作目录内相对路径**：导入 `--file ./orders.csv`、导出 `--output ./out.csv`；绝对路径、或经 `..`/符号链接越出工作目录的 `--output` 会被拒（validation / exit 2）。路径在别处先 `cd` 过去或改成相对路径。
 - **高危操作必须带 `--yes`**：`+db-env-create`、`+db-data-import`、`+db-env-migrate`、`+db-recovery-apply` 缺省会被确认关卡拦下；动手前先用对应的预览命令或 `--dry-run` 看清影响。
 - **时间参数按口语自然传**（`--since`/`--until`/`--target`），格式见末尾。
@@ -154,7 +154,7 @@ lark-cli apps +db-quota-get --app-id app_xxx --environment dev
 
 ## Agent 规则
 
-- 用户说「本地 / 开发库 / 调试库」优先 `--environment dev`，线上排查用 `--environment online`；数据面写操作（导入 / 审计开关）建议先在 `dev` 验再动 `online`。**注意省略 `--environment` 时写操作会落到服务端选中的分支——单环境应用即 `online`（生产）**：不确定应用是否多环境时，写操作显式传 `--environment`；显式 `dev` 在单环境应用上会安全报错（无 dev 分支），正好当「是否多环境」的探针用。
+- 用户说「本地 / 开发库 / 调试库」优先 `--environment dev`，线上排查用 `--environment online`；数据面写操作（导入 / 审计开关）默认先在 `dev` 验再动 `online`。
 - 看表用 `+db-table-list`，看结构用 `+db-table-get`（要建表语句加 `--format pretty`）；`+db-env-create` 仅用于存量单库拆多环境，新建的 full_stack 应用一般不需要。
 - 四个高危命令（`+db-env-create`、`+db-data-import`、`+db-env-migrate`、`+db-recovery-apply`）动手前先看清影响再带 `--yes`：发布 / 恢复先跑对应预览 `+db-env-diff` / `+db-recovery-diff`，导入无预览命令、可先 `--dry-run` 看请求或先在 `--environment dev` 验；不要静默追加 `--yes`，遇 confirmation_required（exit 10）按 lark-shared 协议向用户确认不可逆风险后再补 `--yes` 重试。
 - 导入 / 导出的本地路径用工作目录内相对路径；超大表导出会被行数 / 体积上限拒，改用 `+db-execute` 分批。

skills/lark-mail/references/lark-mail-watch.md

@@ -47,7 +47,7 @@ lark-cli mail +watch --print-output-schema
 |------|------|------|
 | `--mailbox <id>` | `me` | 订阅目标邮箱 |
 | `--msg-format <mode>` | `metadata` | 输出模式：`metadata` / `minimal` / `plain_text_full` / `full` / `event` |
-| `--format <mode>` | `data` | 输出样式：`json`（带 ok/data 信封的 NDJSON 流）/ `data`（裸 NDJSON 流） |
+| `--format <mode>` | `table` | 输出样式：`table` / `json` / `data` |
 | `--folder-ids <json-array>` | — | 文件夹 ID 过滤，如 `["INBOX","SENT"]` |
 | `--folders <json-array>` | — | 文件夹名称过滤（与 `--folder-ids` 取并集） |
 | `--label-ids <json-array>` | — | 标签 ID 过滤，如 `["FLAGGED","IMPORTANT"]` |

skills/lark-slides/SKILL.md

@@ -15,6 +15,7 @@ metadata:
 | 用户需求 | 优先动作 | 关键文档 / 命令 |
 |----------|----------|-----------------|
 | 新建 PPT | 先规划 `slide_plan.json`，再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`slides +create` |
+| 本地生成或校验 SVG Slides / SVGlide 产物 | 先读 `references/svg-slides/README.md`，生成 local publish-ready bundle；发布层另走 `+create-svglide` 后续计划 | `references/svg-slides/README.md`、`scripts/validate_svg_deck.mjs`、`scripts/svg_slides_bundle.mjs` |
 | 已有 PPT 大幅改写 | 多页整页重建用 `+replace-pages`，单页局部编辑用 `+replace-slide` | `xml_presentations.get`、`lark-slides-replace-pages.md`、`lark-slides-edit-workflows.md` |
 | 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
 | 读取或分析已有 PPT | 解析 slides/wiki token，回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `xml_presentations.get`、`xml_presentation.slide.get` |
@@ -29,6 +30,8 @@ metadata:
 
 **CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
 
+**CRITICAL — SVG Slides / SVGlide 与当前 XML/SXSD 工作流是不同协议。两者都使用 960x540 画布，但 SVG Slides 使用 `viewBox="0 0 960 540"` 和 `slide:*` SVG 语义，XML/SXSD 使用 SML XML。处理 SVG Slides 生成或校验时，先读 [`references/svg-slides/README.md`](references/svg-slides/README.md)，不要把 SVG 规则写进 `xml-schema-quick-ref.md`。**
+
 **CRITICAL — PPT 生成与模板编辑硬约束：PPT 的尺寸是 960x540，确保主体内容在页面边界内。多用生图，辅助搜图，必须要图文并茂。不要为了画出一个具象物体而堆叠 3 个以上仅用于拟形的 shape。生成背景图时必须在 prompt 中明确要求不要出现任何文字。用户指定 PPT 模板时，用 lark-drive 技能导入成 lark slides，回读理解每页版式后，直接在该 slides 上编辑，可以填改文字和图片、按需增删模板页，必须严格沿用原版式和字体，只改内容不做设计，完成后回读并微调，凝练文字或缩减字号消除文字溢出，调整 shape 顺序或位置避免文字遮挡。**
 
 **CRITICAL — 新建演示文稿或大幅改写页面时，MUST 先生成 `.lark-slides/plan/<deck-or-task-id>/slide_plan.json`，再生成 XML。先创建对应目录，规划层规则和中间产物生命周期见 [planning-layer.md](references/planning-layer.md)。仅替换一个标题、插入一个块等小型已有页编辑可豁免。**

skills/lark-slides/references/create-svglide-boundary-study.md

@@ -0,0 +1,160 @@
+# create-svglide boundary study
+
+## Goal
+
+Use `slides +create` as the design constraint sample for `slides +create-svglide`.
+
+The central rule is:
+
+```text
+slides +create is a thin publisher for already-authored slide XML.
+slides +create-svglide should be a thin publisher for already-authored SVGlide artifacts.
+```
+
+This document is evidence-first. It separates what the existing shortcut actually does from the broader generation and validation work described by the `lark-slides` skill.
+
+## Source Surface
+
+| Area | Files | Why it matters |
+| --- | --- | --- |
+| Go shortcut implementation | `shortcuts/slides/slides_create.go`, `shortcuts/slides/helpers.go`, `shortcuts/slides/slides_media_upload.go`, `shortcuts/slides/shortcuts.go` | Shows the real runtime boundary of `slides +create`. |
+| Unit tests | `shortcuts/slides/slides_create_test.go` | Shows behavior that must not drift silently. |
+| E2E proof | `tests/cli_e2e/slides/slides_create_workflow_test.go`, `tests/cli_e2e/slides/coverage.md` | Shows what is proven outside the shortcut body. |
+| Skill and references | `skills/lark-slides/SKILL.md`, `skills/lark-slides/references/lark-slides-create.md`, `xml-schema-quick-ref.md`, `validation-checklist.md`, `troubleshooting.md` | Shows which work belongs to agent guidance or scripts instead of Go shortcut code. |
+
+## `slides +create` Responsibility Matrix
+
+| Responsibility | Evidence | Boundary meaning |
+| --- | --- | --- |
+| Register a write shortcut named `slides +create` for user and bot auth | `shortcuts/slides/slides_create.go:24-43`, `shortcuts/slides/shortcuts.go:8-17` | The command is a shortcut wrapper, not a general slide-generation subsystem. |
+| Build a minimal presentation XML shell | `shortcuts/slides/slides_create.go:224-241` | The shortcut creates only the deck container: title plus 960x540 presentation metadata. |
+| Create the online XML presentation | `shortcuts/slides/slides_create.go:125-148` | The first real API call is presentation creation. |
+| Accept optional `--slides` as a JSON array of `<slide>` XML strings | `shortcuts/slides/slides_create.go:40-52` | Page content is supplied by the caller as final XML strings. |
+| Enforce a maximum of 10 inline slide XML strings | `shortcuts/slides/slides_create.go:50-52` | Larger decks must use the lower-level page-create API after container creation. |
+| Detect local image placeholders in submitted XML | `shortcuts/slides/helpers.go:113-153` | The shortcut only interprets one small XML convention: `<img src=\"@path\">`. |
+| Validate placeholder files before creating the presentation | `shortcuts/slides/slides_create.go:53-67` | Avoids creating an orphan deck for missing/oversized local images. |
+| Upload placeholder images and replace them with file tokens | `shortcuts/slides/slides_create.go:163-177`, `shortcuts/slides/slides_media_upload.go:119-138`, `shortcuts/slides/helpers.go:283-309` | Image upload is helper orchestration, not content generation. |
+| Submit each supplied slide XML string to the page-create API | `shortcuts/slides/slides_create.go:179-200` | The shortcut forwards caller-authored XML to the backend. |
+| Report partial progress when page creation fails | `shortcuts/slides/slides_create.go:194-196`, `shortcuts/slides/slides_create_test.go:354-420` | It does not roll back; it tells the caller where to resume. |
+| Output machine-readable creation results | `shortcuts/slides/slides_create.go:150-219` | The output is an API orchestration receipt. |
+| Optionally attempt bot-created deck permission grant | `shortcuts/slides/slides_create.go:215-217`, `shortcuts/slides/slides_create_test.go:66-198` | Bot grant is post-create convenience, not part of content semantics. |
+
+## Behavior Locks From Tests
+
+| Behavior | Evidence | Boundary meaning |
+| --- | --- | --- |
+| User-mode create returns `xml_presentation_id`, `title`, and `url`, without `permission_grant` | `shortcuts/slides/slides_create_test.go:23-63` | User-mode output is a creation receipt, not a validation report. |
+| Missing `--title` becomes `Untitled` in dry-run and execution | `shortcuts/slides/slides_create_test.go:200-253` | Title normalization is a small deterministic convenience that belongs in the shortcut. |
+| `--slides` creates the deck first, then adds pages, then returns `slide_ids` and `slides_added` | `shortcuts/slides/slides_create_test.go:285-352` | Page creation is orchestration after container creation. |
+| `--slides []` behaves like no slides | `shortcuts/slides/slides_create_test.go:532-570` | Empty artifact lists should be explicit no-op additions, not special generators. |
+| Invalid JSON and more than 10 inline slides fail validation with `Param == "--slides"` | `shortcuts/slides/slides_create_test.go:422-505` | Input-contract errors should be structured and routeable. |
+| Missing `xml_presentation_id` from the backend fails | `shortcuts/slides/slides_create_test.go:255-283` | Creation success requires a usable resource id. |
+| URL fallback is local and does not call Drive metas or batch query | `shortcuts/slides/slides_create_test.go:649-688` | Avoid adding extra API dependencies when a local receipt can be built. |
+| Image placeholders are uploaded once per unique path and rewritten before page creation | `shortcuts/slides/slides_create_test.go:751-854` | Asset handling is publish-boundary plumbing, not design work. |
+| Missing local placeholder files fail before any API call | `shortcuts/slides/slides_create_test.go:856-877` | Local artifact existence is a publish-blocking precondition. |
+| Dry-run exposes the API plan shape and placeholder ids | `shortcuts/slides/slides_create_test.go:572-602`, `shortcuts/slides/slides_create_test.go:879-900` | Dry-run should describe orchestration, not execute validation-heavy side effects. |
+| Readback is proven by E2E as a separate follow-up call | `tests/cli_e2e/slides/slides_create_workflow_test.go:32-85`, `tests/cli_e2e/slides/coverage.md:9-16` | Readback is evidence for tests and delivery, not default `Execute` behavior. |
+| Bot permission grant is non-fatal and tri-state: granted, skipped, or failed | `shortcuts/slides/slides_create_test.go:66-198` | Convenience post-actions must not turn creation success into failure. |
+
+## `slides +create` Does Not Do
+
+| Non-responsibility | Evidence | Design implication for `+create-svglide` |
+| --- | --- | --- |
+| Does not generate slide XML from a prompt | `shortcuts/slides/slides_create.go:40-43`, `shortcuts/slides/slides_create.go:158-205` | `+create-svglide` must not become `--topic -> deck`. |
+| Does not deeply validate slide XML semantics | `shortcuts/slides/slides_create.go:44-69` | Only minimal publish-blocking validation belongs in the shortcut. |
+| Does not preview or repair layout | `shortcuts/slides/slides_create.go:125-221` | Preview and repair belong in skill/scripts or a runner before publish. |
+| Does not run readback inside `Execute` | `shortcuts/slides/slides_create.go:125-221`, `tests/cli_e2e/slides/slides_create_workflow_test.go:68-85` | Readback is a test/proof step, not default shortcut behavior. |
+| Does not guarantee atomic creation | `shortcuts/slides/slides_create.go:194-196`, `shortcuts/slides/slides_create_test.go:354-420` | New publish shortcuts should provide recovery context, not hide partial success. |
+| Does not handle more than 10 inline pages | `shortcuts/slides/slides_create.go:18-21`, `shortcuts/slides/slides_create_test.go:441-465` | Bound the first version instead of building a complex batch manager. |
+| Does not own visual quality | `skills/lark-slides/SKILL.md:91-127`, `skills/lark-slides/SKILL.md:153-160` | Visual quality gates belong before the shortcut consumes artifacts. |
+
+## Counterexamples
+
+| Tempting requirement | Why it looks tempting | What `slides +create` teaches |
+| --- | --- | --- |
+| Add readback by default | E2E uses readback to prove persistence. | E2E calls the get API after creation; `Execute` itself stops after outputting the create result. Keep readback optional or outside MVP. |
+| Validate every page semantically before calling the backend | Better local errors sound useful. | `+create` only validates JSON shape, count, and local placeholder files; backend owns XML parsing. For SVGlide, only validate fields required to route and publish. |
+| Run preview lint and auto-repair | SVGlide has preview tooling. | `+create` does not make layout judgments. Preview lint and repair must remain pre-publish tooling. |
+| Accept a prompt and generate the deck | Higher-level UX is attractive. | `+create` consumes final submission artifacts. A prompt-to-deck runner would be a different command or script layer. |
+| Hide partial failures by retrying/rebuilding automatically | It feels friendlier. | `+create` surfaces partial progress instead. Recovery should be explicit and resumable. |
+
+## `slides +create-svglide` Allowed Extra Responsibilities
+
+`+create-svglide` can be slightly heavier than `+create` only where SVGlide's input contract requires it. The extra work must still be publish-boundary work, not generation work.
+
+| Extra responsibility | Allowed because | Limit |
+| --- | --- | --- |
+| Read a SVGlide manifest or run directory | Unlike `--slides`, SVGlide artifacts are file-based. | Normalize to one manifest model immediately; do not infer design intent. |
+| Validate manifest schema and page order | Needed to know what to publish. | Validate shape and required fields only. |
+| Validate page file existence and path safety | Equivalent to `+create` validating `@path` placeholders. | Do not inspect aesthetics or text quality. |
+| Validate publish-required SVGlide fields | The target publish API or parser may require namespace, contract/version, dimensions, or roles before it can accept a page. | Check only required markers; do not rewrite ordinary SVG into protocol SVG in the shortcut. |
+| Upload declared local assets | Equivalent to `+create` uploading `@path` images. | Upload and token replacement only; no asset search or generation. |
+| Submit SVGlide pages to the target publish API | Equivalent to `+create` submitting each slide XML string. | Keep output and partial-progress behavior explicit; do not assume the CLI must convert to XML if the backend can consume SVGlide directly. |
+
+## `slides +create-svglide` Must Not Own
+
+| Responsibility | Owner |
+| --- | --- |
+| Research, outline, design brief, slide content planning | `skills/lark-slides` guidance and external runner/scripts |
+| SVG authoring | Agent or runner before publish |
+| Preview rendering, preview lint, and repair loop | Skill scripts or runner before publish |
+| Visual quality scoring | Skill/scripts/quality gate, not shortcut `Execute` |
+| Readback as default success criterion | E2E or optional verification flag |
+| PPE/Whistle routing as core naming | Environment/profile layer only |
+
+## MVP Scope
+
+Recommended first implementation:
+
+```bash
+lark-cli slides +create-svglide --manifest ./svglide-run/manifest.json --as user
+```
+
+MVP behavior:
+
+1. Parse manifest.
+2. Validate required fields, page order, file existence, path safety, dimensions, and minimal SVGlide contract markers.
+3. Create presentation shell.
+4. Upload local assets declared in the manifest.
+5. Submit pages to the backend.
+6. Output `xml_presentation_id`, `url`, `page_ids` or `slide_ids`, uploaded asset count, and partial-progress context on failure.
+
+MVP exclusions:
+
+1. No prompt input.
+2. No generation stages.
+3. No preview repair.
+4. No default readback.
+5. No PPE-specific command name, directory name, or type name.
+
+## Test Boundary For `+create-svglide`
+
+The first test suite should mirror the shape of `slides +create` tests instead of proving the whole SVGlide generation pipeline.
+
+| Test area | Required proof |
+| --- | --- |
+| Input contract | Invalid manifest, missing page file, unsafe path, and unsupported page count fail with structured params. |
+| Dry-run | Shows create, asset upload, and page publish steps with placeholder presentation id and deterministic step labels. |
+| Asset handling | Duplicate local assets upload once; page payloads reference uploaded tokens before publish. |
+| Partial failure | If the deck exists and page N fails, error includes presentation id, failed page index, and successfully published page count. |
+| Bot grant | Inherit user/bot output behavior from `slides +create`; grant failure is reported but not promoted to create failure. |
+| E2E | Create/publish result is asserted first; optional readback is a separate proof step unless the command explicitly adds a `--readback` contract. |
+
+## Team Finding
+
+The effective research team for this boundary is:
+
+| Role | Scope |
+| --- | --- |
+| Code Reader | Extract runtime responsibilities from Go implementation. |
+| Test Reader | Extract behavior locks and prove what is outside `Execute`. |
+| Skill Boundary Reader | Separate agent/script responsibilities from shortcut responsibilities. |
+| Architect/Skeptic | Reject over-broad scope and map only proven `+create` patterns into `+create-svglide`. |
+
+The team's proof standard is not "we read the files"; it is:
+
+```text
+Every proposed +create-svglide responsibility must map to either:
+1. an existing +create responsibility, or
+2. a minimal extra responsibility forced by SVGlide's artifact input shape.
+```

skills/lark-slides/references/create-svglide-boundary-study.zh.md

@@ -0,0 +1,160 @@
+# create-svglide 边界研究
+
+## 目标
+
+把 `slides +create` 作为 `slides +create-svglide` 的设计约束样本。
+
+核心规则是：
+
+```text
+slides +create 是已经写好的 slide XML 的薄发布器。
+slides +create-svglide 也应该是已经生成好的 SVGlide 产物的薄发布器。
+```
+
+本文档以证据为先，区分现有 shortcut 真实承担的职责，以及 `lark-slides` skill 中描述的更宽泛的生成与验证工作。
+
+## 研究范围
+
+| 范围 | 文件 | 作用 |
+| --- | --- | --- |
+| Go shortcut 实现 | `shortcuts/slides/slides_create.go`、`shortcuts/slides/helpers.go`、`shortcuts/slides/slides_media_upload.go`、`shortcuts/slides/shortcuts.go` | 确认 `slides +create` 的真实运行时边界。 |
+| 单元测试 | `shortcuts/slides/slides_create_test.go` | 确认可被测试锁定、不能随意漂移的行为。 |
+| E2E 证明 | `tests/cli_e2e/slides/slides_create_workflow_test.go`、`tests/cli_e2e/slides/coverage.md` | 确认哪些证明发生在 shortcut 外部。 |
+| Skill 与 references | `skills/lark-slides/SKILL.md`、`skills/lark-slides/references/lark-slides-create.md`、`xml-schema-quick-ref.md`、`validation-checklist.md`、`troubleshooting.md` | 确认哪些工作属于 agent 指导或脚本，而不是 Go shortcut。 |
+
+## `slides +create` 职责矩阵
+
+| 职责 | 证据 | 边界含义 |
+| --- | --- | --- |
+| 注册一个名为 `slides +create` 的写操作 shortcut，支持 user 和 bot 身份 | `shortcuts/slides/slides_create.go:24-43`、`shortcuts/slides/shortcuts.go:8-17` | 这是 shortcut 封装，不是通用幻灯片生成系统。 |
+| 构造最小 presentation XML 外壳 | `shortcuts/slides/slides_create.go:224-241` | shortcut 只创建 deck 容器：标题和 960x540 presentation 元数据。 |
+| 创建在线 XML presentation | `shortcuts/slides/slides_create.go:125-148` | 第一个真实 API 调用是创建 presentation。 |
+| 接收可选 `--slides`，格式为 `<slide>` XML 字符串 JSON 数组 | `shortcuts/slides/slides_create.go:40-52` | 页面内容由调用方以最终 XML 字符串形式提供。 |
+| 限制一次内联提交最多 10 页 slide XML | `shortcuts/slides/slides_create.go:50-52` | 更大的 deck 应先创建容器，再用底层 page-create API 追加页面。 |
+| 检测已提交 XML 里的本地图片占位符 | `shortcuts/slides/helpers.go:113-153` | shortcut 只理解一个很窄的 XML 约定：`<img src="@path">`。 |
+| 创建 presentation 前校验占位符文件 | `shortcuts/slides/slides_create.go:53-67` | 避免因为本地图片缺失或超限而创建孤儿 deck。 |
+| 上传占位符图片并替换为 file token | `shortcuts/slides/slides_create.go:163-177`、`shortcuts/slides/slides_media_upload.go:119-138`、`shortcuts/slides/helpers.go:283-309` | 图片上传是发布边界上的 helper 编排，不是内容生成。 |
+| 把每个调用方提供的 slide XML 字符串提交给 page-create API | `shortcuts/slides/slides_create.go:179-200` | shortcut 把调用方写好的 XML 转交给后端。 |
+| 页面创建失败时报告部分进度 | `shortcuts/slides/slides_create.go:194-196`、`shortcuts/slides/slides_create_test.go:354-420` | 不回滚；告诉调用方从哪里恢复。 |
+| 输出机器可读的创建结果 | `shortcuts/slides/slides_create.go:150-219` | 输出是 API 编排回执。 |
+| bot 创建 deck 后可选尝试给当前用户授权 | `shortcuts/slides/slides_create.go:215-217`、`shortcuts/slides/slides_create_test.go:66-198` | bot grant 是创建后的便利动作，不属于内容语义。 |
+
+## 测试锁定的行为
+
+| 行为 | 证据 | 边界含义 |
+| --- | --- | --- |
+| user 模式创建返回 `xml_presentation_id`、`title`、`url`，不返回 `permission_grant` | `shortcuts/slides/slides_create_test.go:23-63` | user 模式输出是创建回执，不是验证报告。 |
+| 省略 `--title` 时，dry-run 和真实执行都归一为 `Untitled` | `shortcuts/slides/slides_create_test.go:200-253` | 标题归一是适合放在 shortcut 内的小型确定性便利。 |
+| `--slides` 会先创建 deck，再添加页面，最后返回 `slide_ids` 和 `slides_added` | `shortcuts/slides/slides_create_test.go:285-352` | 页面创建是容器创建后的编排。 |
+| `--slides []` 等价于不传 slides | `shortcuts/slides/slides_create_test.go:532-570` | 空产物列表应是明确的无追加操作，不应触发特殊生成逻辑。 |
+| 非法 JSON 和超过 10 个内联 slides 会以 `Param == "--slides"` 的校验错误失败 | `shortcuts/slides/slides_create_test.go:422-505` | 输入契约错误必须结构化，便于调用方路由处理。 |
+| 后端缺少 `xml_presentation_id` 时失败 | `shortcuts/slides/slides_create_test.go:255-283` | 创建成功必须拿到可用资源 id。 |
+| URL fallback 在本地构造，不调用 Drive metas 或 batch query | `shortcuts/slides/slides_create_test.go:649-688` | 能用本地回执构造的内容，不应增加额外 API 依赖。 |
+| 图片占位符按唯一路径上传一次，并在页面创建前完成替换 | `shortcuts/slides/slides_create_test.go:751-854` | 素材处理是发布边界的管道能力，不是设计工作。 |
+| 本地占位符文件缺失时，在任何 API 调用前失败 | `shortcuts/slides/slides_create_test.go:856-877` | 本地产物存在性是发布前置条件。 |
+| Dry-run 暴露 API 计划形状和占位 id | `shortcuts/slides/slides_create_test.go:572-602`、`shortcuts/slides/slides_create_test.go:879-900` | Dry-run 应描述编排计划，而不是执行重型校验副作用。 |
+| Readback 在 E2E 中作为单独 follow-up 调用证明 | `tests/cli_e2e/slides/slides_create_workflow_test.go:32-85`、`tests/cli_e2e/slides/coverage.md:9-16` | Readback 是测试和交付证据，不是默认 `Execute` 行为。 |
+| Bot 授权是非致命三态：granted、skipped、failed | `shortcuts/slides/slides_create_test.go:66-198` | 便利性的后置动作不应把创建成功升级成失败。 |
+
+## `slides +create` 不负责的事情
+
+| 非职责 | 证据 | 对 `+create-svglide` 的设计含义 |
+| --- | --- | --- |
+| 不从 prompt 生成 slide XML | `shortcuts/slides/slides_create.go:40-43`、`shortcuts/slides/slides_create.go:158-205` | `+create-svglide` 不能变成 `--topic -> deck`。 |
+| 不深度校验 slide XML 语义 | `shortcuts/slides/slides_create.go:44-69` | shortcut 内只应放发布阻塞级的最小校验。 |
+| 不预览或修复布局 | `shortcuts/slides/slides_create.go:125-221` | preview 和 repair 属于发布前的 skill/scripts 或 runner。 |
+| 不在 `Execute` 内做 readback | `shortcuts/slides/slides_create.go:125-221`、`tests/cli_e2e/slides/slides_create_workflow_test.go:68-85` | Readback 是测试/证明步骤，不是默认 shortcut 行为。 |
+| 不保证原子创建 | `shortcuts/slides/slides_create.go:194-196`、`shortcuts/slides/slides_create_test.go:354-420` | 新发布类 shortcut 应提供恢复上下文，而不是隐藏部分成功。 |
+| 不处理超过 10 个内联页面 | `shortcuts/slides/slides_create.go:18-21`、`shortcuts/slides/slides_create_test.go:441-465` | 第一版应设边界，而不是一开始实现复杂批处理器。 |
+| 不负责视觉质量 | `skills/lark-slides/SKILL.md:91-127`、`skills/lark-slides/SKILL.md:153-160` | 视觉质量门禁应发生在 shortcut 消费产物之前。 |
+
+## 反例
+
+| 诱人的需求 | 为什么看起来合理 | `slides +create` 给出的约束 |
+| --- | --- | --- |
+| 默认加入 readback | E2E 用 readback 证明持久化。 | E2E 是创建后另调 get API；`Execute` 输出创建结果后即结束。Readback 应保持可选或放在 MVP 外。 |
+| 调后端前语义校验每一页 | 本地错误更友好。 | `+create` 只校验 JSON 形状、页数、本地占位符文件；XML 解析由后端负责。SVGlide 也只校验发布路由必需字段。 |
+| 运行 preview lint 并自动 repair | SVGlide 有 preview 工具链。 | `+create` 不做布局判断。Preview lint 和 repair 应留在发布前工具链。 |
+| 接受 prompt 并生成 deck | 高层 UX 很吸引人。 | `+create` 消费最终提交物。Prompt-to-deck runner 应是另一层命令或脚本。 |
+| 通过自动重试/重建隐藏部分失败 | 看起来更友好。 | `+create` 暴露部分进度。恢复应该显式、可续跑。 |
+
+## `slides +create-svglide` 允许新增的职责
+
+`+create-svglide` 只能在 SVGlide 输入契约强制要求的地方比 `+create` 稍重。新增工作仍必须属于发布边界，而不是生成边界。
+
+| 额外职责 | 允许原因 | 限制 |
+| --- | --- | --- |
+| 读取 SVGlide manifest 或 run directory | 与 `--slides` 不同，SVGlide 产物是文件型产物。 | 立即归一化为一个 manifest 模型；不要推断设计意图。 |
+| 校验 manifest schema 和页序 | 需要知道要发布什么。 | 只校验形状和必填字段。 |
+| 校验页面文件存在性和路径安全 | 等价于 `+create` 校验 `@path` 占位符。 | 不检查美观度或文本质量。 |
+| 校验发布必需的 SVGlide 字段 | 目标发布 API 或 parser 可能需要 namespace、contract/version、尺寸或 role 才能接收页面。 | 只检查必需标记；不要在 shortcut 中把普通 SVG 重写成协议 SVG。 |
+| 上传声明的本地素材 | 等价于 `+create` 上传 `@path` 图片。 | 只做上传和 token 替换；不做素材搜索或生成。 |
+| 把 SVGlide 页面提交给目标发布 API | 等价于 `+create` 提交每个 slide XML 字符串。 | 保持输出和部分进度语义明确；如果后端能直接消费 SVGlide，不要假设 CLI 必须转 XML。 |
+
+## `slides +create-svglide` 必须不拥有的职责
+
+| 职责 | 所属边界 |
+| --- | --- |
+| research、outline、design brief、slide content planning | `skills/lark-slides` 指导和外部 runner/scripts |
+| SVG authoring | agent 或 runner，在发布前完成 |
+| preview rendering、preview lint、repair loop | skill scripts 或 runner，在发布前完成 |
+| 视觉质量评分 | skill/scripts/quality gate，不属于 shortcut `Execute` |
+| readback 作为默认成功标准 | E2E 或可选验证 flag |
+| PPE/Whistle 路由进入核心命名 | 只能属于环境/profile 层 |
+
+## MVP 范围
+
+推荐第一版实现：
+
+```bash
+lark-cli slides +create-svglide --manifest ./svglide-run/manifest.json --as user
+```
+
+MVP 行为：
+
+1. 解析 manifest。
+2. 校验必填字段、页序、文件存在性、路径安全、尺寸、最小 SVGlide contract 标记。
+3. 创建 presentation 外壳。
+4. 上传 manifest 声明的本地素材。
+5. 把页面提交给后端。
+6. 输出 `xml_presentation_id`、`url`、`page_ids` 或 `slide_ids`、上传素材数量，以及失败时的部分进度上下文。
+
+MVP 排除项：
+
+1. 不接受 prompt 输入。
+2. 不包含生成阶段。
+3. 不做 preview repair。
+4. 不默认 readback。
+5. 不在命令名、目录名或类型名中包含 PPE。
+
+## `+create-svglide` 测试边界
+
+第一版测试应镜像 `slides +create` 的测试形状，而不是证明完整 SVGlide 生成流水线。
+
+| 测试范围 | 必须证明 |
+| --- | --- |
+| 输入契约 | 非法 manifest、缺失页面文件、不安全路径、不支持的页数以结构化 param 失败。 |
+| Dry-run | 展示 create、asset upload、page publish 步骤，包含占位 presentation id 和确定性的 step label。 |
+| 素材处理 | 重复本地素材只上传一次；页面 payload 在发布前引用已上传 token。 |
+| 部分失败 | deck 已存在但第 N 页失败时，错误包含 presentation id、失败页序号、已成功发布页数。 |
+| Bot grant | 继承 `slides +create` 的 user/bot 输出行为；grant 失败不升级成 create 失败。 |
+| E2E | 先断言 create/publish 结果；可选 readback 作为单独证明步骤，除非命令显式加入 `--readback` 契约。 |
+
+## Team 结论
+
+适合研究这个边界的 team 是：
+
+| 角色 | 范围 |
+| --- | --- |
+| Code Reader | 从 Go 实现中抽取运行时职责。 |
+| Test Reader | 抽取行为锁定点，并证明哪些行为不在 `Execute` 内。 |
+| Skill Boundary Reader | 区分 agent/script 职责和 shortcut 职责。 |
+| Architect/Skeptic | 拒绝过宽 scope，只把已被 `+create` 证明的模式映射到 `+create-svglide`。 |
+
+这个 team 的证明标准不是“读过文件”，而是：
+
+```text
+每一个 proposed +create-svglide 职责都必须映射到：
+1. 一个已有 +create 职责；或
+2. 一个由 SVGlide 产物输入形态强制产生的最小额外职责。
+```

skills/lark-slides/references/svg-slides/README.md

@@ -0,0 +1,41 @@
+# SVG Slides Local Generation
+
+This reference family is for local SVG Slides generation and validation.
+
+It is not the Lark Slides XML/SXSD workflow and it is not the publish shortcut. Use it to produce a local publish-ready bundle that a future `slides +create-svglide` publisher can consume.
+
+## Read Routes
+
+| Task | Read first | Then read |
+|---|---|---|
+| Generate a new SVG deck | `workflow.md` | `design-brief.md`, `protocol.md`, `authoring-rules.md`, `visual-design.md`, `validation.md` |
+| Repair protocol failures | `validation.md` | `protocol.md`, `authoring-rules.md` |
+| Improve visual quality | `visual-design.md` | `design-brief.md`, `workflow.md` |
+| Use charts | `chart-workflow.md` | `protocol.md`, `validation.md` |
+| Continue an existing deck | `editing-existing-decks.md` | `workflow.md`, `protocol.md` |
+| Audit provenance | `source/split-manifest.json` | `source/full.debranded.md` |
+
+## Boundary
+
+Generation and validation produce a local publish-ready bundle.
+
+A future SVG Slides publisher consumes this bundle. That publishing path is intentionally outside this reference family.
+
+A local bundle may set `publish_ready=true`; it must not claim it is published.
+
+## Canvas Decision
+
+This CLI adaptation uses a 960x540 SVG canvas: `viewBox="0 0 960 540"`.
+
+The source snapshot is preserved for provenance and coverage audit. Where the source describes a different default canvas, the CLI adaptation layer intentionally normalizes generated SVG Slides to 960x540.
+
+## Required Local Gates
+
+1. `node skills/lark-slides/scripts/validate_svg_deck.mjs <deck-dir> --json`
+2. `node skills/lark-slides/scripts/svg_slides_bundle.mjs <deck-dir> --title "<title>"`
+3. Browser text-boundary check when Playwright is available.
+
+## Source Coverage
+
+- Covers manifest sections: title
+- Coverage mode: routing entry; source text is preserved in `source/full.debranded.md`, while this file points workers to the coverage-preserving split docs.

skills/lark-slides/references/svg-slides/authoring-rules.md

@@ -0,0 +1,79 @@
+# SVG Slides Authoring Rules
+
+## Required Authoring Pattern
+
+Write complete slide files. A slide edit is not a fragment, patch, or HTML page.
+
+Use this order:
+
+1. Optional `<defs>`.
+2. One background as the first rendered child.
+3. Top-level shapes, images, charts, groups, and optional notes.
+
+Every rendered element that the slide engine must understand needs the appropriate `slide:role`. Do not depend on generic browser rendering when the protocol has an explicit semantic role.
+
+## Forbidden Constructs
+
+Do not use:
+
+- `<style>` blocks;
+- `class=`;
+- `<div>` or `<section>` wrappers in text `foreignObject`;
+- bare text under `foreignObject`;
+- SVG `<text>`;
+- SVG `<marker>`;
+- hex colors;
+- named colors;
+- `none` for `fill` or `stroke`;
+- role-less primitives in the rendered slide body.
+
+## Text Boxes
+
+Use plain text boxes for text-only content:
+
+```xml
+<foreignObject slide:role="shape" slide:shape-type="text" x="96" y="96" width="640" height="120" style="font-size:32px;color:rgba(15,23,42,1);line-height:1.2">
+  <p xmlns="http://www.w3.org/1999/xhtml" style="margin:0px;font-size:32px;color:rgba(15,23,42,1)">Main argument</p>
+</foreignObject>
+```
+
+Use shape-with-text only when the object is truly one styled box with one text block. If the card has multiple parts, use `<g slide:role="group">`.
+
+## Image Elements
+
+Use images when there is a real image asset or generated visual. The SVG file references the local asset path.
+
+Informational images such as charts, diagrams, screenshots, and infographics must preserve their original ratio. Decorative images may be composed more freely, but should still fit the resolved design brief.
+
+Unless the user explicitly requests no images, cover, section divider, and closing pages should use a large hero image or generated visual. Full-bleed image backgrounds use `<image slide:role="background">`; large non-background images use `<image slide:role="image" slide:shape-type="image">`.
+
+When text sits on an image, place a semi-transparent `<rect slide:role="shape" slide:shape-type="shape">` scrim or a solid text zone after the image and before the text. Do not use SVG `<mask>` for this readability layer.
+
+Generated cover, section divider, or closing images must not contain baked-in text. Render text as slide text on top of the image.
+
+## Chart Embeds
+
+A chart is an external SVG sidecar referenced by:
+
+```xml
+<rect slide:role="chart" href="resources/charts/example.svg" x="120" y="180" width="800" height="500"/>
+```
+
+Do not hand-draw a chart from primitives when the slide's point depends on a real quantitative data series. Use the chart workflow to generate the sidecar first.
+
+## Custom Paths
+
+Custom paths require accurate bounds. `slide:width` and `slide:height` describe the real extent of the path data, not the full canvas.
+
+If a path has not been normalized, measure its bounding box before writing the final slide. Oversized path boxes make selection, hit testing, and layout misleading.
+
+## Grouped Cards
+
+Use `<g slide:role="group">` for a multi-element cluster: card background, badge, icon, title, body, chart, image, or connector. Each child still carries its own role.
+
+Do not use `<g slide:role="shape">` as a generic container. It is only for the shape-with-text form.
+
+## Source Coverage
+
+- Covers manifest sections: slides_edit_tool, image_usage, compute_custom_shape_bbox_tool
+- Coverage mode: preserve authoring constraints and tool semantics that affect generated SVG structure.

skills/lark-slides/references/svg-slides/chart-workflow.md

@@ -0,0 +1,64 @@
+# SVG Slides Chart Workflow
+
+## When To Use A Chart
+
+Use a chart when the slide's point depends on a real quantitative series:
+
+- trend;
+- multi-category comparison;
+- part-to-whole split;
+- distribution;
+- ranking;
+- two-dimensional positioning.
+
+For single numbers or trivial two-bucket comparisons, prefer a large text callout unless the comparison needs a chart to be understood.
+
+## When Not To Use A Chart
+
+Do not generate a chart for vague, unsourced, decorative, or invented data. Do not choose a chart type because the raw data happens to look compatible; choose it because the takeaway requires that representation.
+
+When in doubt, a sorted bar chart is safer than a pie or doughnut.
+
+## Chart Sidecar Contract
+
+A chart is generated as an SVG sidecar before slide authoring and embedded by reference.
+
+The generation request must decide the takeaway first. The takeaway must be faithful to the data and short enough to guide chart design.
+
+The request must include:
+
+- chart type;
+- JSON data matching that type;
+- style matching the destination slide;
+- actual on-slide width and height;
+- output path under `resources/charts/`.
+
+The declared chart width should match the embed width. Chart internals derive text size from width. Do not declare a wide chart and embed it in a narrow slot.
+
+## Embed Contract
+
+Embed a generated chart with:
+
+```xml
+<rect slide:role="chart" href="resources/charts/name.svg" x="120" y="180" width="800" height="500"/>
+```
+
+The embed width and height must match the chart sidecar's intended display size. Keep a 16:10-ish chart area when possible to avoid letterboxing.
+
+One chart should carry one distinct insight. Pair charts with short callouts or labels, and vary chart composition across the deck.
+
+## Validation Notes
+
+Static deck validation confirms the chart placeholder shape, not the correctness of the chart sidecar data. Review chart sidecars for:
+
+- source-backed data;
+- truthful takeaway;
+- readable labels;
+- width at or above the practical floor;
+- matching palette;
+- intact `href`.
+
+## Source Coverage
+
+- Covers manifest sections: generate_svg_chart_tool
+- Coverage mode: preserve chart generation, data contract, rendering constraints, and validation expectations.

skills/lark-slides/references/svg-slides/design-brief.md

@@ -0,0 +1,80 @@
+# SVG Slides Design Brief
+
+## Inputs
+
+Resolve the design brief after these inputs are known:
+
+- topic and goal;
+- audience;
+- delivery mode;
+- language;
+- page count when known;
+- source material;
+- user-fixed brand, color, or content constraints;
+- one to three short visual-direction phrases.
+
+Do not ask the user to choose tone, density, palette, or typography unless they volunteered hard constraints.
+
+## Output Contract
+
+The brief must produce:
+
+- `narrative_spine`;
+- `depth`;
+- `tone`;
+- `visual_system`.
+
+These outputs govern outline, content density, wording, asset choices, typography, color, layout, and decoration.
+
+## narrative_spine
+
+`narrative_spine` defines the slide sequence discipline. It is the default source of order, sectioning, and narrative movement.
+
+The user can override it by giving or editing an outline. After that point, the user outline wins.
+
+## depth
+
+`depth` decides altitude and density:
+
+- how much context each slide carries;
+- what to include and exclude;
+- how many main points per slide;
+- how source evidence should appear;
+- whether a page should split instead of cram.
+
+## tone
+
+`tone` controls writing style and evidence posture. It should reflect the audience and delivery mode.
+
+Presented decks can use shorter on-slide wording because the speaker carries context. Self-read decks need more complete explanatory text but still must avoid walls of text.
+
+## visual_system
+
+`visual_system` is the authority for look and feel. It should include:
+
+- color logic;
+- typography category and treatment;
+- layout grammar;
+- imagery or material direction;
+- page-role imagery defaults for cover, section divider, and closing pages;
+- decoration and motif rules;
+- constraints to avoid.
+
+Unless the user explicitly requests no images, `visual_system` must specify how cover, section divider, and closing pages use a high-impact hero image or generated visual. The brief should describe the imagery subject, treatment, crop attitude, and how foreground text stays readable.
+
+Font mapping must preserve the same category and treatment. Do not swap serif and sans, ignore uppercase treatment, or pick generic fonts when the brief calls for a distinctive style.
+
+## How It Drives Generation
+
+Use the brief in this order:
+
+1. Shape the outline from `narrative_spine`.
+2. Size the content from `depth`.
+3. Write titles and evidence from `tone`.
+4. Build the deck-level style from `visual_system`.
+5. Author each slide's layout from the content logic plus the visual system.
+
+## Source Coverage
+
+- Covers manifest sections: resolve_design_brief
+- Coverage mode: preserve design brief inputs, output contract, and downstream influence on outline and page authoring.

skills/lark-slides/references/svg-slides/editing-existing-decks.md

@@ -0,0 +1,39 @@
+# SVG Slides Editing Existing Decks
+
+## Continue Existing Deck
+
+When the user asks to continue, edit, extend, or repair an existing uploaded deck, operate on the existing converted project instead of recreating from scratch.
+
+Preserve every existing page unless the user asks to change it. A page with minimal content should remain minimal if that is what the source deck contained.
+
+## Preserve Existing Pages
+
+For text or layout changes, edit only the target slide files. Preserve styling by default. Restyle only when the user explicitly asks.
+
+Preserve media, chart, video, and audio blocks verbatim when the request does not touch them.
+
+## Add Or Delete Pages
+
+Add pages through the organize workflow, then author the new standalone SVG pages.
+
+Delete only pages the user asked to remove. Do not rerun the new-deck outline workflow over an existing deck; it can overwrite existing slide files and lose original pages.
+
+## Template Reference Boundary
+
+An uploaded reference can mean two different things:
+
+- Continue or edit this deck: preserve and modify that deck.
+- Create a new deck inspired by this reference: author fresh SVG using the normal create workflow.
+
+Clarify when the user's wording does not identify which behavior they want.
+
+## PPTX Conversion Boundary
+
+Converted decks may contain imported chart placeholders or media. Preserve legacy chart references unless the user asks to update chart data, type, theme, or emphasis.
+
+If a chart is resized materially, regenerate the chart sidecar with the new dimensions rather than only squeezing the existing placeholder.
+
+## Source Coverage
+
+- Covers manifest sections: slide_organize_tool, slides_convert_tool, slides_parse_template_tool
+- Coverage mode: preserve existing-deck continuation, conversion, and template parsing boundaries without turning them into publish behavior.

skills/lark-slides/references/svg-slides/examples/chart-embed.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:slide="https://slides.bytedance.com/ns" slide:role="slide" id="chart_embed" viewBox="0 0 960 540">
+  <rect slide:role="background" x="0" y="0" width="960" height="540" fill="rgba(255,255,255,1)"/>
+  <foreignObject slide:role="shape" slide:shape-type="text" x="80" y="56" width="680" height="72" style="font-size:36px;font-family:DM Sans,PingFang SC,Noto Sans SC,Arial,sans-serif;color:rgba(17,24,39,1);font-weight:800;line-height:1.15;text-align:left;vertical-align:top;letter-spacing:0px;padding:0px">
+    <h2 xmlns="http://www.w3.org/1999/xhtml" style="margin:0px;font-size:36px;line-height:1.15;color:rgba(17,24,39,1);letter-spacing:0px">Chart is a referenced sidecar</h2>
+  </foreignObject>
+  <rect slide:role="chart" href="resources/charts/example_bar.svg" x="80" y="160" width="560" height="350"/>
+  <foreignObject slide:role="shape" slide:shape-type="text" x="690" y="190" width="190" height="118" style="font-size:19px;font-family:DM Sans,PingFang SC,Noto Sans SC,Arial,sans-serif;color:rgba(55,65,81,1);font-weight:500;line-height:1.38;text-align:left;vertical-align:top;letter-spacing:0px;padding:0px">
+    <p xmlns="http://www.w3.org/1999/xhtml" style="margin:0px;font-size:19px;line-height:1.38;color:rgba(55,65,81,1);letter-spacing:0px">The chart payload lives outside the slide and is referenced by href.</p>
+  </foreignObject>
+</svg>

skills/lark-slides/references/svg-slides/examples/group-card.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:slide="https://slides.bytedance.com/ns" slide:role="slide" id="group_card" viewBox="0 0 960 540">
+  <defs>
+    <linearGradient id="card_grad" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="rgba(255,255,255,1)"/>
+      <stop offset="100%" stop-color="rgba(226,232,240,1)"/>
+    </linearGradient>
+  </defs>
+  <rect slide:role="background" x="0" y="0" width="960" height="540" fill="rgba(241,245,249,1)"/>
+  <g slide:role="group" id="card_primary">
+    <rect slide:role="shape" slide:shape-type="round-rect" x="120" y="140" width="520" height="300" rx="24" ry="24" fill="url(#card_grad)" stroke="rgba(148,163,184,1)" stroke-width="1"/>
+    <circle slide:role="shape" slide:shape-type="circle" cx="180" cy="206" r="26" fill="rgba(37,99,235,1)"/>
+    <foreignObject slide:role="shape" slide:shape-type="text" x="224" y="178" width="340" height="50" style="font-size:28px;font-family:DM Sans,PingFang SC,Noto Sans SC,Arial,sans-serif;color:rgba(15,23,42,1);font-weight:800;line-height:1.2;text-align:left;vertical-align:top;letter-spacing:0px;padding:0px">
+      <h2 xmlns="http://www.w3.org/1999/xhtml" style="margin:0px;font-size:28px;line-height:1.2;color:rgba(15,23,42,1);letter-spacing:0px">Grouped card</h2>
+    </foreignObject>
+    <foreignObject slide:role="shape" slide:shape-type="text" x="154" y="264" width="420" height="86" style="font-size:20px;font-family:DM Sans,PingFang SC,Noto Sans SC,Arial,sans-serif;color:rgba(51,65,85,1);font-weight:500;line-height:1.38;text-align:left;vertical-align:top;letter-spacing:0px;padding:0px">
+      <p xmlns="http://www.w3.org/1999/xhtml" style="margin:0px;font-size:20px;line-height:1.38;color:rgba(51,65,85,1);letter-spacing:0px">A card is a group; every visual child still carries its own slide role.</p>
+    </foreignObject>
+  </g>
+</svg>

skills/lark-slides/references/svg-slides/examples/minimal-slide.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:slide="https://slides.bytedance.com/ns" slide:role="slide" id="minimal_slide" viewBox="0 0 960 540">
+  <rect slide:role="background" x="0" y="0" width="960" height="540" fill="rgba(248,250,252,1)"/>
+  <foreignObject slide:role="shape" slide:shape-type="text" x="80" y="80" width="760" height="92" style="font-size:42px;font-family:DM Sans,PingFang SC,Noto Sans SC,Arial,sans-serif;color:rgba(15,23,42,1);font-weight:800;line-height:1.12;text-align:left;vertical-align:top;letter-spacing:0px;padding:0px">
+    <h1 xmlns="http://www.w3.org/1999/xhtml" style="margin:0px;font-size:42px;line-height:1.12;color:rgba(15,23,42,1);letter-spacing:0px">One protocol-compliant SVG slide</h1>
+  </foreignObject>
+</svg>

skills/lark-slides/references/svg-slides/protocol.md

@@ -0,0 +1,94 @@
+# SVG Slides Protocol
+
+## Canvas
+
+- Each page is one standalone SVG file.
+- Root must contain `xmlns="http://www.w3.org/2000/svg"`.
+- Root must contain `xmlns:slide="https://slides.bytedance.com/ns"`.
+- Root must contain `slide:role="slide"`.
+- Root must contain an `id`.
+- Root must contain `viewBox="0 0 960 540"`.
+- Child coordinates are in viewBox units.
+- Do not rely on HTML document behavior. SVG nodes use SVG semantics; XHTML appears only inside approved `foreignObject` children.
+- This 960x540 canvas is the CLI adaptation target. The preserved source snapshot may mention other defaults, but generated local bundles must use 960x540.
+
+## Background
+
+- Exactly one rendered background is required.
+- Optional `<defs>` may appear first.
+- The first rendered child after optional `<defs>` must be a `<rect>` or `<image>` with `slide:role="background"`.
+- Background must cover the full canvas.
+- Gradient backgrounds must reference gradients declared in the same slide's `<defs>`.
+- A full-bleed image background should be an `<image slide:role="background">`.
+- Text scrims over image backgrounds are normal shape overlays after the background, not additional backgrounds.
+
+## Text
+
+- Plain text uses `foreignObject slide:role="shape" slide:shape-type="text"`.
+- Text `foreignObject` needs numeric `x`, `y`, `width`, and `height`.
+- The first direct XHTML child must be `p`, `ul`, `ol`, `h1`, `h2`, `h3`, or `small`.
+- Do not wrap text in `div` or `section`.
+- Do not put bare text directly under `foreignObject`.
+- Text style belongs in `style`.
+- `font-size` must include `px`.
+- Text color must be `rgb(...)` or `rgba(...)`.
+- Text boxes must be sized to fit; static validation does not prove rendered wrapping.
+
+## Shapes And Groups
+
+- Geometry needs `slide:role="shape"` and a meaningful `slide:shape-type`.
+- Common geometry includes `rect`, `ellipse`, `circle`, `path`, and `line`.
+- Multi-element cards use `<g slide:role="group">`.
+- Children inside a group still keep their own `slide:role`.
+- A shape-with-text group is only for one geometry plus one text block. Cards with badges, icons, charts, or multiple text blocks must be regular groups.
+- Custom paths must declare a meaningful `slide:width` and `slide:height` that match the path's real bounding box.
+
+## Lines
+
+- Lines use `<line slide:role="shape" slide:shape-type="line">`.
+- Arrows use `slide:start-arrow` or `slide:end-arrow`.
+- SVG marker arrows are forbidden.
+
+## Images
+
+- Images use `<image slide:role="image" slide:shape-type="image" href="...">`.
+- Informational images preserve source aspect ratio.
+- Do not wrap a single image in a group unless it is truly part of a larger multi-element composition.
+- Borders and shadows belong on the image element itself when used.
+
+## Charts
+
+- Charts use `<rect slide:role="chart" href="..." x="..." y="..." width="..." height="...">`.
+- The rect is a chart placeholder; it is not a drawn rectangle.
+- Place charts at top level or inside `<g slide:role="group">`.
+- Preserve chart `href` verbatim unless the user asks to change chart data, type, emphasis, theme, or source.
+
+## Notes
+
+- Speaker notes are optional and do not render on canvas.
+- At most one `<slide:note>` may appear.
+- Notes contain direct paragraph children.
+
+## Colors
+
+- Use `rgb(...)`, `rgba(...)`, or `url(#id)`.
+- Do not use hex colors.
+- Do not use named colors.
+- Do not use `none` for `fill` or `stroke`; use `rgba(0,0,0,0)` for transparent fills.
+
+## Animation
+
+- Animation is part of delivery, not decoration.
+- Most slides should be static.
+- Presented decks may use progressive reveal for complex steps, charts, processes, timelines, or comparisons.
+- Self-read, formal, board, or consulting decks should read fully without clicks.
+- Use at most three builds on a slide.
+- Use one effect type per slide.
+- Animated elements need explicit `id`.
+- Animate top-level elements or top-level groups.
+- Use one deck-level page transition when needed; do not vary transition style slide by slide.
+
+## Source Coverage
+
+- Covers manifest sections: svg_reference, svg_document_rules
+- Coverage mode: preserve hard SVG protocol requirements from the source while applying the CLI canvas adaptation to 960x540; visual guidance belongs in `visual-design.md`, not here.

skills/lark-slides/references/svg-slides/source/split-manifest.json

@@ -0,0 +1,25 @@
+{
+  "version": "svg-slides.split-manifest.v1",
+  "source": "skills/lark-slides/references/svg-slides/source/full.debranded.md",
+  "source_export": "/Users/bytedance/Documents/Codex/2026-07-01/https-bytedance-larkoffice-com-docx-kncld7xr5ohwonxhksncz3lxnvd/outputs/lark_doc_KnCLd7xr5ohWONxhKsncZ3Lxnvd/full.debranded.md",
+  "source_role": "provenance_and_coverage_authority_not_default_runtime_context",
+  "sections": [
+    {"id": "title", "lines": [1, 1], "target": "README.md"},
+    {"id": "system_prompt_workflow", "lines": [3, 196], "target": "workflow.md"},
+    {"id": "svg_reference", "lines": [198, 865], "target": "protocol.md"},
+    {"id": "resolve_design_brief", "lines": [867, 1080], "target": "design-brief.md"},
+    {"id": "deck_design_reference_catalog", "lines": [1082, 1234], "target": "visual-design.md"},
+    {"id": "slide_outline_tool", "lines": [1236, 1254], "target": "workflow.md"},
+    {"id": "activate_slides_edit_tool", "lines": [1256, 1262], "target": "workflow.md"},
+    {"id": "slides_edit_tool", "lines": [1264, 1281], "target": "authoring-rules.md"},
+    {"id": "svg_document_rules", "lines": [1283, 1287], "target": "protocol.md"},
+    {"id": "image_usage", "lines": [1289, 1291], "target": "authoring-rules.md"},
+    {"id": "incremental_processing", "lines": [1293, 1331], "target": "workflow.md"},
+    {"id": "finish_slides_edit_tool", "lines": [1333, 1339], "target": "validation.md"},
+    {"id": "slide_organize_tool", "lines": [1341, 1347], "target": "editing-existing-decks.md"},
+    {"id": "compute_custom_shape_bbox_tool", "lines": [1349, 1355], "target": "authoring-rules.md"},
+    {"id": "generate_svg_chart_tool", "lines": [1357, 2356], "target": "chart-workflow.md"},
+    {"id": "slides_convert_tool", "lines": [2358, 2395], "target": "editing-existing-decks.md"},
+    {"id": "slides_parse_template_tool", "lines": [2397, 2420], "target": "editing-existing-decks.md"}
+  ]
+}

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

@@ -0,0 +1,120 @@
+# SVG Slides Validation
+
+## Static Protocol Validator
+
+Run:
+
+```bash
+node skills/lark-slides/scripts/validate_svg_deck.mjs <deck-dir-or-slides-dir> --json
+```
+
+The validator checks hard protocol rules:
+
+- standalone SVG root;
+- `slide:role="slide"`;
+- required namespaces;
+- `viewBox="0 0 960 540"`;
+- background order;
+- forbidden style blocks and CSS classes;
+- forbidden text wrappers;
+- color syntax;
+- text `font-size` units;
+- line role and arrow semantics;
+- XML parseability.
+
+The validator is a hard gate for publish-ready local bundles.
+
+## Browser Text Boundary Check
+
+Static XML cannot prove final rendered wrapping, CJK font fallback, or actual text height. Run browser text-boundary QA when Playwright is available:
+
+```bash
+node skills/lark-slides/scripts/svg_slides_browser_text_bounds.mjs <deck-dir-or-slides-dir> --out /tmp/svg-slides-text-bounds.json
+```
+
+If Playwright is unavailable, the script exits 2 and explains the missing optional dependency.
+
+## Bundle Manifest
+
+Run:
+
+```bash
+node skills/lark-slides/scripts/svg_slides_bundle.mjs <deck-dir> --title "<title>"
+```
+
+The bundle manifest records:
+
+- protocol version;
+- title;
+- slide list;
+- validation receipt paths;
+- `publish_ready=true`;
+- `published=false`.
+
+## Receipt Requirements
+
+A local publish-ready bundle needs:
+
+- `manifest.json`;
+- `receipts/validate_svg_deck.json`;
+- optional browser text-boundary receipt when browser QA ran;
+- slide files listed in deterministic order.
+
+## What Passing Validation Does Not Prove
+
+Passing validation does not prove visual excellence, source quality, chart truth, or backend acceptance. It proves that the generated local SVG files obey the hard protocol rules represented by the validator.
+
+Always separate:
+
+- protocol pass;
+- browser text-boundary pass;
+- visual design review;
+- live publish proof.
+
+## Local Publish-Ready Bundle
+
+Run:
+
+```bash
+node skills/lark-slides/scripts/svg_slides_bundle.mjs <deck-dir> --title "<deck title>"
+```
+
+The command writes:
+
+- `manifest.json`
+- `receipts/validate_svg_deck.json`
+
+The manifest uses:
+
+```json
+{
+  "version": "svglide.manifest.v1",
+  "protocol": "svg-slides.v1",
+  "size": {"width": 960, "height": 540},
+  "publish_ready": true,
+  "published": false
+}
+```
+
+`publish_ready=true` means local static validation passed. It does not mean the deck was published to Lark Slides.
+
+## Browser Text Boundary QA
+
+When Playwright is available in the development environment, run:
+
+```bash
+node skills/lark-slides/scripts/svg_slides_browser_text_bounds.mjs <deck-dir> --out receipts/preview_text_bounds.json
+```
+
+Exit codes:
+
+- `0`: no text-boundary problems.
+- `1`: rendered text overflow was detected.
+- `2`: the script could not run, for example Playwright is unavailable.
+
+This browser check is a generation-quality gate. It is not a publish API proof.
+
+## Source Coverage
+
+- Covers manifest sections: finish_slides_edit_tool
+- Coverage mode: preserve finish/validation gates and explicitly separate protocol pass from visual quality pass.

skills/lark-slides/references/svg-slides/visual-design.md

@@ -0,0 +1,74 @@
+# SVG Slides Visual Design
+
+## Typography
+
+Use real font families that are likely to render. Keep a stable display/body pairing across the deck.
+
+Titles, hero numbers, and key labels may use display fonts. Body text should use readable fonts. English and CJK decks need compatible font choices rather than generic fallback everywhere.
+
+Do not switch typography per slide without a structural reason.
+
+## Layout Freedom
+
+SVG Slides gives full coordinate-level layout control. Use that control to encode the page's logic.
+
+Start each slide by identifying the relationship in the content:
+
+- comparison;
+- sequence;
+- timeline;
+- cycle;
+- hierarchy;
+- matrix or quadrant;
+- funnel;
+- part-to-whole;
+- cause to effect;
+- evidence to implication.
+
+Then compose a bespoke structure using position, scale, alignment, grouping, flow direction, connectors, depth, and contrast. A layout invented for the slide's actual logic is better than a canned diagram.
+
+## Visual Differentiation
+
+Every substantive slide should have a visual idea: image, chart, diagram, process, comparison, spatial map, large number, table-like structure, or custom shape system.
+
+Avoid repeating title-plus-bullets. Reuse deck-level motif and style, not the exact same page layout.
+
+Cover, section divider, and closing pages are not exceptions. Unless the user explicitly requests no images, make these pages image-led with a high-impact hero image or generated visual. Text over imagery must use an intentional readability treatment, such as a translucent scrim or solid text zone, instead of relying on contrast by accident.
+
+## Density
+
+Density comes from audience and delivery mode. Split rather than cram when a slide needs more than one central idea.
+
+Each slide should defend one central idea. Content slide titles should be declarative arguments, not topic labels. Cover, section, and closing slides can use shorter labels.
+
+## Anti-Patterns
+
+Avoid:
+
+- generic white slides with bullets only;
+- the same card grid on every page;
+- low-contrast text;
+- decorative lines crossing text;
+- filler agenda or Q&A pages in short decks;
+- placeholder images;
+- unverified data visualization;
+- text walls;
+- overusing animation.
+
+## Remaining Human Judgment
+
+Static validation proves protocol shape, not taste. A deck can pass validation and still be visually weak.
+
+Review visual quality separately:
+
+- Does the layout express the slide's logic?
+- Does each slide have a clear central claim?
+- Are data and claims source-backed?
+- Is typography intentional and consistent?
+- Is the page readable in a browser at expected size?
+- Does the deck vary composition while staying in one visual system?
+
+## Source Coverage
+
+- Covers manifest sections: deck_design_reference_catalog
+- Coverage mode: preserve visual quality rules and examples as generation guidance; do not collapse them into generic style advice.

skills/lark-slides/references/svg-slides/workflow.md

@@ -0,0 +1,98 @@
+# SVG Slides Workflow
+
+## Layer Boundary
+
+This workflow owns local SVG deck generation and local validation. It does not call live APIs, choose a PPE lane, or prove backend acceptance of the generated payload.
+
+The output is a local publish-ready bundle: standalone SVG slide files, source notes, optional assets, validation receipts, and a manifest. It is not published.
+
+## Phase 1: Understand Request
+
+Decide whether the user wants a new deck, a continuation of an existing deck, a repair pass, or a visual-quality pass. Clarify only when the target file, target slides, audience, delivery mode, or requested outcome is genuinely ambiguous.
+
+Audience means the final viewer, not the creator. A specific audience can drive density and evidence style directly. Generic labels such as "users", "clients", or "team" are not specific enough for broad generation unless the user asks not to be interrupted.
+
+## Phase 2: Settle Goal Audience Delivery
+
+Settle three values before designing slides:
+
+- `goal`: what the presentation should make the viewer understand or decide.
+- `audience`: who will read or watch it.
+- `delivery_mode`: `presented` when a speaker talks over it, `self_read` when it must stand alone.
+
+Do not ask the user to pick tone, palette, density, or style. Those are inferred later by the design brief.
+
+## Phase 3: Build Source Material
+
+Broad topic-only requests require real source material. Search snippets, memory, and internal knowledge are not enough.
+
+Collect full source text before drafting claims. Save a local research file with data points, claims, caveats, and source references. Every important claim or number used later must be traceable from `slide_content.md` back to this source material.
+
+## Phase 4: Resolve Design Brief
+
+Create a design brief after goal, audience, delivery mode, language, page count, and source material are known.
+
+The brief must include:
+
+- `narrative_spine`: the sequence logic and discipline of the deck.
+- `depth`: altitude, density, include/exclude rules, and main points per slide.
+- `tone`: writing and evidence style.
+- `visual_system`: color, typography, layout, imagery, material, and decoration direction.
+
+The design brief is authoritative for the generated deck. Do not override it with generic taste while authoring pages.
+
+## Phase 5: Confirm Outline
+
+For broad topics, create an actual slide sequence, not a chapter list. Use the user's explicit page count when given. Otherwise use 8-12 substantive slides for normal decks, unless the user explicitly asked for a short deck.
+
+When the user gave a detailed outline, use it. When the user reorders, removes, adds, or rewrites slides, the user's outline wins over the brief's `narrative_spine`.
+
+## Phase 6: Write slide_content
+
+Write `slide_content.md` before SVG authoring.
+
+`slide_content.md` records the structure, slide roles, key material, data points, claims, quotes, and source references. It does not lock exact final sentences, image paths, chart layout, or final page composition.
+
+## Phase 7: Lock Visual Direction And Plan Visuals
+
+Translate `visual_system` into concrete deck-level style:
+
+- `aesthetic_direction`: the design language and mood from the brief.
+- `color_palette`: consistent deck palette, expressed later as `rgb(...)` / `rgba(...)`.
+- `typography`: a stable display/body pairing that matches the brief's category and treatment.
+- `visual_assets`: per-slide image and chart needs, including aspect ratio and placement intent.
+
+Unless the user explicitly requests no images, cover, section divider, and closing pages default to a high-impact hero image or generated visual. Record the intended asset, crop/aspect ratio, placement, and text-readability overlay treatment in `visual_assets`; do not leave these page roles as text-only by default.
+
+Plan charts before writing slides. Any real quantitative series that supports a slide's point should use the chart workflow rather than a hand-drawn fake chart.
+
+## Phase 8: Author SVG Pages
+
+Each page is a complete standalone SVG document. Compose freely for the page's content logic. Do not stamp out a fixed template pattern.
+
+For each page, record authoring intent before writing:
+
+- the central idea;
+- the layout relationship being encoded;
+- visual assets used;
+- animation decision, or `static`;
+- expected validation risks.
+
+Do not regenerate the whole deck structure after slide files have been authored. Add or remove pages through the existing-deck workflow.
+
+## Output Bundle
+
+The local bundle should contain:
+
+- `slides/*.svg`: one standalone SVG slide per page;
+- `slide_content.md`: source-backed content plan;
+- `research_notes.md` when source material was gathered;
+- `resources/` for chart/image sidecars;
+- `manifest.json` from `svg_slides_bundle.mjs`;
+- `receipts/validate_svg_deck.json` from the static validator;
+- optional browser text-boundary receipt.
+
+## Source Coverage
+
+- Covers manifest sections: system_prompt_workflow, slide_outline_tool, activate_slides_edit_tool, incremental_processing
+- Coverage mode: preserve workflow semantics from the source while replacing product-specific tool names with local generation stages.

skills/lark-slides/scripts/svg_slides_browser_text_bounds.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+
+function fail(message, code = 2) {
+  console.error(message);
+  process.exit(code);
+}
+
+const args = process.argv.slice(2);
+const targetArg = args.find((arg) => !arg.startsWith("--"));
+const outIndex = args.indexOf("--out");
+const outPath = outIndex >= 0 ? args[outIndex + 1] : "";
+
+if (!targetArg) {
+  fail("Usage: node skills/lark-slides/scripts/svg_slides_browser_text_bounds.mjs <deck-dir-or-slides-dir> [--out <json-path>]");
+}
+
+let chromium;
+try {
+  ({ chromium } = await import("playwright"));
+} catch {
+  fail("playwright is not installed; install it in a dev environment before browser text-boundary QA", 2);
+}
+
+const target = path.resolve(targetArg);
+const slidesDir = fs.existsSync(path.join(target, "slides")) ? path.join(target, "slides") : target;
+if (!fs.existsSync(slidesDir)) {
+  fail(`Slides directory not found: ${slidesDir}`);
+}
+
+const slideFiles = fs.readdirSync(slidesDir).filter((file) => file.endsWith(".svg")).sort();
+if (!slideFiles.length) {
+  fail(`No .svg files found in ${slidesDir}`);
+}
+
+const browser = await chromium.launch({ headless: true });
+const page = await browser.newPage({ viewport: { width: 960, height: 540 }, deviceScaleFactor: 1 });
+const results = [];
+
+for (const file of slideFiles) {
+  const abs = path.join(slidesDir, file);
+  const svg = fs.readFileSync(abs, "utf8");
+  await page.setContent(`<!doctype html><html><body style="margin:0">${svg}</body></html>`, { waitUntil: "load" });
+  const problems = await page.evaluate(() => {
+    return [...document.querySelectorAll("foreignObject")].flatMap((node, index) => {
+      if (node.getAttribute("slide:role") !== "shape" || node.getAttribute("slide:shape-type") !== "text") {
+        return [];
+      }
+
+      const box = node.getBoundingClientRect();
+      const children = [...node.children];
+      if (!children.length) {
+        return [{ index: index + 1, reason: "empty_text_object" }];
+      }
+
+      return children.map((child) => {
+        const childBox = child.getBoundingClientRect();
+        const overflowX = childBox.left < box.left - 0.5 || childBox.right > box.right + 0.5;
+        const overflowY = childBox.top < box.top - 0.5 || childBox.bottom > box.bottom + 0.5;
+        if (!overflowX && !overflowY) return null;
+        return {
+          index: index + 1,
+          reason: "text_bounds_overflow",
+          box: { x: box.x, y: box.y, width: box.width, height: box.height },
+          childBox: { x: childBox.x, y: childBox.y, width: childBox.width, height: childBox.height }
+        };
+      }).filter(Boolean);
+    });
+  });
+  results.push({ file: path.relative(process.cwd(), abs), problemCount: problems.length, problems });
+}
+
+await browser.close();
+
+const problemCount = results.reduce((sum, item) => sum + item.problemCount, 0);
+const report = { status: problemCount === 0 ? "passed" : "failed", problemCount, results };
+const json = `${JSON.stringify(report, null, 2)}\n`;
+if (outPath) {
+  fs.mkdirSync(path.dirname(path.resolve(outPath)), { recursive: true });
+  fs.writeFileSync(outPath, json);
+}
+process.stdout.write(json);
+process.exit(problemCount === 0 ? 0 : 1);

skills/lark-slides/scripts/svg_slides_bundle.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+function fail(message, code = 2) {
+  console.error(message);
+  process.exit(code);
+}
+
+const args = process.argv.slice(2);
+const deckArg = args.find((arg) => !arg.startsWith("--"));
+const titleIndex = args.indexOf("--title");
+const title = titleIndex >= 0 ? args[titleIndex + 1] : "";
+
+if (!deckArg || !title) {
+  fail("Usage: node skills/lark-slides/scripts/svg_slides_bundle.mjs <deck-dir> --title <title>");
+}
+
+const root = path.resolve(deckArg);
+const slidesDir = fs.existsSync(path.join(root, "slides")) ? path.join(root, "slides") : root;
+if (!fs.existsSync(slidesDir)) {
+  fail(`Slides directory not found: ${slidesDir}`);
+}
+
+const validator = path.resolve("skills/lark-slides/scripts/validate_svg_deck.mjs");
+const validate = spawnSync("node", [validator, root, "--json"], { encoding: "utf8" });
+if (!validate.stdout.trim()) {
+  process.stderr.write(validate.stderr);
+  process.exit(validate.status || 1);
+}
+
+const receipt = JSON.parse(validate.stdout);
+fs.mkdirSync(path.join(root, "receipts"), { recursive: true });
+fs.writeFileSync(path.join(root, "receipts", "validate_svg_deck.json"), `${JSON.stringify(receipt, null, 2)}\n`);
+if (receipt.totalErrors !== 0) {
+  fail(`SVG deck is not publish-ready: ${receipt.totalErrors} validation error(s)`, 1);
+}
+
+const slideFiles = fs.readdirSync(slidesDir)
+  .filter((file) => file.endsWith(".svg"))
+  .sort();
+
+const pages = slideFiles.map((file, index) => {
+  const abs = path.join(slidesDir, file);
+  const raw = fs.readFileSync(abs);
+  return {
+    id: path.basename(file, ".svg"),
+    index: index + 1,
+    file: path.relative(root, abs).split(path.sep).join("/"),
+    sha256: crypto.createHash("sha256").update(raw).digest("hex")
+  };
+});
+
+const manifest = {
+  version: "svglide.manifest.v1",
+  protocol: "svg-slides.v1",
+  title,
+  size: { width: 960, height: 540 },
+  publish_ready: true,
+  published: false,
+  pages,
+  receipts: {
+    validate_svg_deck: "receipts/validate_svg_deck.json"
+  }
+};
+
+fs.writeFileSync(path.join(root, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+console.log(JSON.stringify({ ok: true, manifest: path.join(root, "manifest.json"), pages: pages.length }, null, 2));

skills/lark-slides/scripts/svg_slides_bundle_test.mjs

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+
+const script = path.resolve("skills/lark-slides/scripts/svg_slides_bundle.mjs");
+
+function tempDeck() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "svg-slides-bundle-"));
+  fs.mkdirSync(path.join(root, "slides"));
+  return root;
+}
+
+const validSlide = `<svg xmlns="http://www.w3.org/2000/svg" xmlns:slide="https://slides.bytedance.com/ns" slide:role="slide" id="bundle_slide" viewBox="0 0 960 540">
+  <rect slide:role="background" x="0" y="0" width="960" height="540" fill="rgba(255,255,255,1)"/>
+  <foreignObject slide:role="shape" slide:shape-type="text" x="80" y="80" width="600" height="80" style="font-size:32px;font-family:DM Sans,PingFang SC,Noto Sans SC,Arial,sans-serif;color:rgba(15,23,42,1);line-height:1.2;letter-spacing:0px;padding:0px">
+    <p xmlns="http://www.w3.org/1999/xhtml" style="margin:0px;font-size:32px;color:rgba(15,23,42,1)">Bundle</p>
+  </foreignObject>
+</svg>`;
+
+test("bundle builder writes manifest and validation receipt", () => {
+  const root = tempDeck();
+  fs.writeFileSync(path.join(root, "slides", "slide_01.svg"), validSlide);
+  const result = spawnSync("node", [script, root, "--title", "Bundle Test"], { encoding: "utf8" });
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, "manifest.json"), "utf8"));
+  assert.equal(manifest.version, "svglide.manifest.v1");
+  assert.equal(manifest.protocol, "svg-slides.v1");
+  assert.equal(manifest.title, "Bundle Test");
+  assert.deepEqual(manifest.size, { width: 960, height: 540 });
+  assert.equal(manifest.publish_ready, true);
+  assert.equal(manifest.published, false);
+  assert.equal(manifest.pages.length, 1);
+  assert.match(manifest.pages[0].sha256, /^[a-f0-9]{64}$/);
+  const receipt = JSON.parse(fs.readFileSync(path.join(root, "receipts", "validate_svg_deck.json"), "utf8"));
+  assert.equal(receipt.totalErrors, 0);
+});
+
+test("bundle builder rejects invalid SVG deck", () => {
+  const root = tempDeck();
+  fs.writeFileSync(path.join(root, "slides", "slide_01.svg"), validSlide.replace("rgba(255,255,255,1)", "#fff"));
+  const result = spawnSync("node", [script, root, "--title", "Invalid"], { encoding: "utf8" });
+  assert.equal(result.status, 1);
+  assert.match(result.stderr, /not publish-ready/);
+  assert.equal(fs.existsSync(path.join(root, "receipts", "validate_svg_deck.json")), true);
+  assert.equal(fs.existsSync(path.join(root, "manifest.json")), false);
+});

skills/lark-slides/scripts/svg_slides_source_coverage_check.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+
+const rootArg = process.argv.find((arg) => !arg.startsWith("--") && arg !== process.argv[1] && arg !== process.argv[0]);
+const root = path.resolve(rootArg || "skills/lark-slides/references/svg-slides");
+const json = process.argv.includes("--json");
+const manifestPath = path.join(root, "source", "split-manifest.json");
+
+function readText(file) {
+  return fs.readFileSync(file, "utf8");
+}
+
+function coverageBlock(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === "## Source Coverage");
+  if (start === -1) return "";
+  const block = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (/^#{1,2}\s+/.test(lines[i])) break;
+    block.push(lines[i]);
+  }
+  return block.join("\n");
+}
+
+function coverageIds(block) {
+  const match = block.match(/^- Covers manifest sections:\s*(.+)$/m);
+  if (!match) return [];
+  return match[1].split(",").map((value) => value.trim()).filter(Boolean);
+}
+
+const errors = [];
+if (!fs.existsSync(manifestPath)) {
+  errors.push(`missing manifest: ${manifestPath}`);
+}
+
+const manifest = errors.length === 0 ? JSON.parse(readText(manifestPath)) : { sections: [] };
+const sectionsById = new Map(manifest.sections.map((section) => [section.id, section]));
+const seen = new Map();
+
+if (fs.existsSync(root)) {
+  for (const entry of fs.readdirSync(root)) {
+    if (!entry.endsWith(".md")) continue;
+    const filePath = path.join(root, entry);
+    const block = coverageBlock(readText(filePath));
+    if (!block) {
+      errors.push(`${entry}: missing ## Source Coverage`);
+      continue;
+    }
+    const ids = coverageIds(block);
+    if (ids.length === 0) {
+      errors.push(`${entry}: missing "- Covers manifest sections:" line`);
+      continue;
+    }
+    for (const id of ids) {
+      const section = sectionsById.get(id);
+      if (!section) {
+        errors.push(`${entry}: unknown manifest section "${id}"`);
+        continue;
+      }
+      if (section.target !== entry) {
+        errors.push(`${entry}: section "${id}" belongs to ${section.target}`);
+      }
+      const files = seen.get(id) || [];
+      files.push(entry);
+      seen.set(id, files);
+    }
+  }
+}
+
+for (const section of manifest.sections) {
+  const files = seen.get(section.id) || [];
+  if (files.length === 0) {
+    errors.push(`${section.id}: not covered by ${section.target}`);
+  }
+  if (files.length > 1) {
+    errors.push(`${section.id}: covered multiple times by ${files.join(", ")}`);
+  }
+}
+
+const report = {
+  root,
+  manifest: manifestPath,
+  sectionCount: manifest.sections.length,
+  coveredCount: seen.size,
+  errors
+};
+
+if (json) {
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} else if (errors.length === 0) {
+  console.log(`Source coverage OK: ${report.coveredCount}/${report.sectionCount} sections`);
+} else {
+  console.error(`Source coverage failed: ${errors.length} errors`);
+  for (const error of errors) console.error(`- ${error}`);
+}
+
+process.exit(errors.length === 0 ? 0 : 1);

skills/lark-slides/scripts/svg_slides_source_coverage_check_test.mjs

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+
+const script = path.resolve("skills/lark-slides/scripts/svg_slides_source_coverage_check.mjs");
+
+function tempRoot() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "svg-slides-coverage-"));
+  fs.mkdirSync(path.join(root, "source"), { recursive: true });
+  return root;
+}
+
+function writeManifest(root, sections) {
+  fs.writeFileSync(path.join(root, "source", "split-manifest.json"), JSON.stringify({
+    version: "svg-slides.split-manifest.v1",
+    source: "source/full.debranded.md",
+    sections
+  }, null, 2));
+}
+
+function run(root) {
+  return spawnSync("node", [script, root, "--json"], { encoding: "utf8" });
+}
+
+test("passes when each manifest section is covered by its target file", () => {
+  const root = tempRoot();
+  writeManifest(root, [{ id: "workflow", lines: [1, 10], target: "workflow.md" }]);
+  fs.writeFileSync(path.join(root, "workflow.md"), "# Workflow\n\n## Source Coverage\n\n- Covers manifest sections: workflow\n");
+  const result = run(root);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(JSON.parse(result.stdout).errors.length, 0);
+});
+
+test("fails when a section is missing from Source Coverage", () => {
+  const root = tempRoot();
+  writeManifest(root, [{ id: "protocol", lines: [1, 10], target: "protocol.md" }]);
+  fs.writeFileSync(path.join(root, "protocol.md"), "# Protocol\n\n## Source Coverage\n\n- Covers manifest sections: other\n");
+  const result = run(root);
+  assert.equal(result.status, 1);
+  const report = JSON.parse(result.stdout);
+  assert.ok(report.errors.some((error) => error.includes("unknown manifest section")));
+  assert.ok(report.errors.some((error) => error.includes("not covered")));
+});
+
+test("fails when a section is declared by the wrong target file", () => {
+  const root = tempRoot();
+  writeManifest(root, [{ id: "visual", lines: [1, 10], target: "visual-design.md" }]);
+  fs.writeFileSync(path.join(root, "workflow.md"), "# Workflow\n\n## Source Coverage\n\n- Covers manifest sections: visual\n");
+  const result = run(root);
+  assert.equal(result.status, 1);
+  assert.ok(JSON.parse(result.stdout).errors.some((error) => error.includes("belongs to visual-design.md")));
+});

skills/lark-slides/scripts/validate_svg_deck.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+function usage() {
+  console.error("Usage: node skills/lark-slides/scripts/validate_svg_deck.mjs <deck-dir-or-slides-dir> [--json]");
+}
+
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const targetArg = args.find((arg) => !arg.startsWith("--"));
+
+if (!targetArg) {
+  usage();
+  process.exit(2);
+}
+
+const target = path.resolve(targetArg);
+const slidesDir = fs.existsSync(path.join(target, "slides")) ? path.join(target, "slides") : target;
+
+if (!fs.existsSync(slidesDir)) {
+  console.error(`Slides directory not found: ${slidesDir}`);
+  process.exit(2);
+}
+
+const slideFiles = fs.readdirSync(slidesDir)
+  .filter((file) => file.endsWith(".svg"))
+  .sort()
+  .map((file) => path.join(slidesDir, file));
+
+if (!slideFiles.length) {
+  console.error(`No .svg files found in: ${slidesDir}`);
+  process.exit(2);
+}
+
+function commandExists(name) {
+  const result = spawnSync("sh", ["-lc", `command -v ${name}`], { encoding: "utf8" });
+  return result.status === 0;
+}
+
+function checkXml(file, errors) {
+  if (!commandExists("xmllint")) {
+    errors.push({
+      rule: "xml.valid",
+      severity: "warn",
+      message: "xmllint is unavailable; XML parser check skipped",
+    });
+    return;
+  }
+  const result = spawnSync("xmllint", ["--noout", file], { encoding: "utf8" });
+  if (result.status !== 0) {
+    errors.push({
+      rule: "xml.valid",
+      severity: "error",
+      message: (result.stderr || result.stdout || "xmllint failed").trim(),
+    });
+  }
+}
+
+function firstElementAfterDefs(svg) {
+  const rootOpen = svg.match(/<svg\b[^>]*>/);
+  if (!rootOpen) return null;
+  let inner = svg.slice(rootOpen.index + rootOpen[0].length, svg.lastIndexOf("</svg>")).trim();
+  if (inner.startsWith("<defs")) {
+    const end = inner.indexOf("</defs>");
+    if (end === -1) return null;
+    inner = inner.slice(end + "</defs>".length).trim();
+  }
+  return inner.match(/^<([a-zA-Z][\w:-]*)\b([^>]*)>/)?.[0] || null;
+}
+
+function stripDefs(svg) {
+  return svg.replace(/<defs\b[\s\S]*?<\/defs>/g, "");
+}
+
+function attrValue(tag, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return tag.match(new RegExp(`${escaped}="([^"]*)"`))?.[1] || "";
+}
+
+function isColorValueAllowed(value) {
+  return /^(rgba?\([^)]*\)|url\(#[-\w]+\))$/.test(value.trim());
+}
+
+function checkSlide(file) {
+  const rel = path.relative(process.cwd(), file);
+  const svg = fs.readFileSync(file, "utf8");
+  const errors = [];
+
+  checkXml(file, errors);
+
+  const root = svg.match(/<svg\b[^>]*>/)?.[0] || "";
+  if (!root) {
+    errors.push({ rule: "svg.root", severity: "error", message: "missing <svg> root" });
+  } else {
+    if (!/xmlns="http:\/\/www\.w3\.org\/2000\/svg"/.test(root)) {
+      errors.push({ rule: "svg.root.xmlns", severity: "error", message: "missing SVG namespace" });
+    }
+    if (!/xmlns:slide="https:\/\/slides\.bytedance\.com\/ns"/.test(root)) {
+      errors.push({ rule: "svg.root.slide-xmlns", severity: "error", message: "missing slide namespace" });
+    }
+    if (!/slide:role="slide"/.test(root)) {
+      errors.push({ rule: "svg.root.slide-role", severity: "error", message: "root must have slide:role=\"slide\"" });
+    }
+    if (!/id="[^"]+"/.test(root)) {
+      errors.push({ rule: "svg.root.id", severity: "error", message: "root must have id" });
+    }
+    if (!/viewBox="0 0 960 540"/.test(root)) {
+      errors.push({ rule: "svg.root.viewBox", severity: "error", message: "expected viewBox=\"0 0 960 540\"" });
+    }
+  }
+
+  if (/<presentation\b/.test(svg)) {
+    errors.push({ rule: "svg.no-presentation-wrapper", severity: "error", message: "single slide file must not wrap with <presentation>" });
+  }
+
+  const first = firstElementAfterDefs(svg);
+  const backgroundCount = (svg.match(/slide:role="background"/g) || []).length;
+  if (backgroundCount !== 1) {
+    errors.push({ rule: "background.count", severity: "error", message: `expected exactly one background, found ${backgroundCount}` });
+  }
+  if (!first || !/^(<rect\b|<image\b)/.test(first) || !/slide:role="background"/.test(first)) {
+    errors.push({ rule: "background.first-child", severity: "error", message: "first rendered child after optional <defs> must be the background" });
+  }
+
+  const bodyNoDefs = stripDefs(svg);
+  const forbidden = [
+    { rule: "forbid.style-block", re: /<style\b/, message: "slide SVG must not rely on <style> blocks" },
+    { rule: "forbid.css-class", re: /\bclass="/, message: "slide SVG must not rely on CSS classes" },
+    { rule: "forbid.div-wrapper", re: /<div\b/, message: "text foreignObject must not contain <div>" },
+    { rule: "forbid.section-wrapper", re: /<section\b/, message: "text foreignObject must not contain <section>" },
+    { rule: "forbid.svg-text", re: /<text\b/, message: "use foreignObject rich text, not SVG <text>" },
+    { rule: "forbid.svg-marker", re: /\bmarker-(start|end|mid)=|<marker\b/, message: "line arrowheads must use slide:* arrow attributes, not SVG marker" },
+    { rule: "forbid.legacy-fontSize", re: /\bfontSize="/, message: "text visual properties must be in style, not legacy fontSize attribute" },
+    { rule: "forbid.legacy-bold", re: /\bbold="/, message: "text visual properties must be in style, not legacy bold attribute" },
+  ];
+  for (const item of forbidden) {
+    if (item.re.test(bodyNoDefs)) {
+      errors.push({ rule: item.rule, severity: "error", message: item.message });
+    }
+  }
+
+  for (const match of bodyNoDefs.matchAll(/\b(fill|stroke|stop-color)="([^"]+)"/g)) {
+    const [, attr, value] = match;
+    if (!isColorValueAllowed(value)) {
+      errors.push({
+        rule: "color.attr",
+        severity: "error",
+        message: `${attr} must be rgb(...), rgba(...), or url(#...); got ${JSON.stringify(value)}`,
+      });
+    }
+  }
+  for (const match of bodyNoDefs.matchAll(/(?:^|;)\s*color\s*:\s*([^;"]+)/g)) {
+    const value = match[1].trim();
+    if (!/^rgba?\([^)]*\)$/.test(value)) {
+      errors.push({
+        rule: "color.css",
+        severity: "error",
+        message: `CSS color must be rgb(...) or rgba(...); got ${JSON.stringify(value)}`,
+      });
+    }
+  }
+
+  const foreignObjects = [...svg.matchAll(/<foreignObject\b([^>]*)>([\s\S]*?)<\/foreignObject>/g)];
+  for (const [index, match] of foreignObjects.entries()) {
+    const attrText = match[1];
+    const inner = match[2].trim();
+    const label = `foreignObject #${index + 1}`;
+    const isTextObject = /slide:role="shape"/.test(attrText) && /slide:shape-type="text"/.test(attrText);
+    if (!isTextObject) continue;
+
+    for (const attr of ["x", "y", "width", "height"]) {
+      if (!new RegExp(`\\b${attr}="[-0-9.]+`).test(attrText)) {
+        errors.push({ rule: "text.geometry", severity: "error", message: `${label} missing numeric ${attr}` });
+      }
+    }
+
+    const styleText = attrValue(match[0], "style");
+    if (!/font-size:\s*\d+(?:\.\d+)?px/.test(styleText)) {
+      errors.push({ rule: "text.style.font-size", severity: "error", message: `${label} missing font-size with px suffix in style` });
+    }
+    if (!/color:\s*rgba?\(/.test(styleText)) {
+      errors.push({ rule: "text.style.color", severity: "error", message: `${label} missing rgb/rgba color in style` });
+    }
+
+    if (!/^<(p|ul|ol|h1|h2|h3|small)\b/.test(inner)) {
+      errors.push({
+        rule: "text.direct-child",
+        severity: "error",
+        message: `${label} first direct child must be p/ul/ol/h1/h2/h3/small, got ${inner.slice(0, 40) || "empty"}`,
+      });
+    }
+    if (/<(div|section)\b/.test(inner)) {
+      errors.push({ rule: "text.no-wrapper", severity: "error", message: `${label} contains an invalid wrapper element` });
+    }
+    if (/^([^<]|\s)+$/.test(inner)) {
+      errors.push({ rule: "text.no-bare-text", severity: "error", message: `${label} contains bare text instead of xhtml children` });
+    }
+  }
+
+  for (const match of bodyNoDefs.matchAll(/<line\b([^>]*)>/g)) {
+    const attrs = match[1];
+    if (!/slide:role="shape"/.test(attrs) || !/slide:shape-type="line"/.test(attrs)) {
+      errors.push({ rule: "line.role", severity: "error", message: "line must carry slide:role=\"shape\" and slide:shape-type=\"line\"" });
+    }
+    if (!/\bstroke="rgba?\(/.test(attrs)) {
+      errors.push({ rule: "line.stroke", severity: "error", message: "line must have rgb/rgba stroke" });
+    }
+  }
+
+  return { file: rel, errorCount: errors.filter((item) => item.severity === "error").length, errors };
+}
+
+const results = slideFiles.map(checkSlide);
+const totalErrors = results.reduce((sum, result) => sum + result.errorCount, 0);
+const report = {
+  target: path.relative(process.cwd(), target),
+  slidesDir: path.relative(process.cwd(), slidesDir),
+  slideCount: slideFiles.length,
+  totalErrors,
+  results,
+};
+
+if (json) {
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  console.log(`SVG deck validation: ${report.target}`);
+  console.log(`Slides: ${report.slideCount}`);
+  console.log(`Errors: ${report.totalErrors}`);
+  for (const result of results) {
+    const status = result.errorCount ? "FAIL" : "PASS";
+    console.log(`\n[${status}] ${result.file}`);
+    for (const error of result.errors) {
+      if (error.severity === "warn") {
+        console.log(`  WARN ${error.rule}: ${error.message}`);
+      } else {
+        console.log(`  ${error.rule}: ${error.message}`);
+      }
+    }
+  }
+}
+
+process.exit(totalErrors ? 1 : 0);

skills/lark-slides/scripts/validate_svg_deck_test.mjs

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+
+const script = path.resolve("skills/lark-slides/scripts/validate_svg_deck.mjs");
+
+function tempDeck() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "svg-slides-validator-"));
+  fs.mkdirSync(path.join(root, "slides"));
+  return root;
+}
+
+function writeSlide(root, name, body) {
+  fs.writeFileSync(path.join(root, "slides", name), body);
+}
+
+function runValidator(root) {
+  return spawnSync("node", [script, root, "--json"], { encoding: "utf8" });
+}
+
+const validSlide = `<svg xmlns="http://www.w3.org/2000/svg" xmlns:slide="https://slides.bytedance.com/ns" slide:role="slide" id="valid" viewBox="0 0 960 540">
+  <rect slide:role="background" x="0" y="0" width="960" height="540" fill="rgba(255,255,255,1)"/>
+  <foreignObject slide:role="shape" slide:shape-type="text" x="80" y="80" width="600" height="80" style="font-size:32px;font-family:DM Sans,PingFang SC,Noto Sans SC,Arial,sans-serif;color:rgba(15,23,42,1);line-height:1.2;letter-spacing:0px;padding:0px">
+    <p xmlns="http://www.w3.org/1999/xhtml" style="margin:0px;font-size:32px;color:rgba(15,23,42,1)">Valid</p>
+  </foreignObject>
+</svg>`;
+
+test("valid SVG deck passes", () => {
+  const root = tempDeck();
+  writeSlide(root, "slide_01.svg", validSlide);
+
+  const result = runValidator(root);
+  assert.equal(result.status, 0, result.stderr);
+
+  const report = JSON.parse(result.stdout);
+  assert.equal(report.slideCount, 1);
+  assert.equal(report.totalErrors, 0);
+});
+
+test("invalid SVG deck reports protocol errors", () => {
+  const root = tempDeck();
+  writeSlide(root, "slide_01.svg", `<svg xmlns="http://www.w3.org/2000/svg" id="bad" viewBox="0 0 960 540">
+    <style>.t{fill:red}</style>
+    <rect width="960" height="540" fill="#fff"/>
+    <foreignObject slide:role="shape" slide:shape-type="text" x="80" y="80" width="300" height="80" style="font-size:32;color:#111">
+      <div xmlns="http://www.w3.org/1999/xhtml"><p>Bad</p></div>
+    </foreignObject>
+  </svg>`);
+
+  const result = runValidator(root);
+  assert.equal(result.status, 1);
+
+  const report = JSON.parse(result.stdout);
+  const rules = report.results.flatMap((item) => item.errors.map((error) => error.rule));
+  assert.ok(rules.includes("svg.root.slide-xmlns"));
+  assert.ok(rules.includes("svg.root.slide-role"));
+  assert.ok(rules.includes("background.first-child"));
+  assert.ok(rules.includes("forbid.style-block"));
+  assert.ok(rules.includes("forbid.div-wrapper"));
+  assert.ok(rules.includes("color.attr"));
+  assert.ok(rules.includes("text.style.font-size"));
+  assert.ok(rules.includes("text.style.color"));
+});
+
+test("examples directory remains protocol-valid", () => {
+  const examples = path.resolve("skills/lark-slides/references/svg-slides/examples");
+  const result = spawnSync("node", [script, examples, "--json"], { encoding: "utf8" });
+  assert.equal(result.status, 0, result.stderr);
+  const report = JSON.parse(result.stdout);
+  assert.equal(report.slideCount, 3);
+  assert.equal(report.totalErrors, 0);
+});

skills/lark-vc-agent/SKILL.md

@@ -73,14 +73,12 @@ metadata:
    - 再根据 `note_id`、`minute_token` 和用户意图，按 [`lark-vc`](../lark-vc/SKILL.md) 的产物决策读取正文、逐字稿或妙记。
    - 想看参会人快照：用 `vc meeting get --with-participants`（见 [`lark-vc`](../lark-vc/SKILL.md)）
 5. **默认必须使用** **`--page-all`**，除非用户明确要求“只查一页”，或确实需要控制返回体大小。
-6. 命令默认输出结构化事件契约：`meeting`、`identity`、`events`、`warnings`、`has_more`、`page_token`；`identity` 表示当前读取身份，事件 actor 含 `participant_type`、`role` 和可读 `label`，事件细节保留在 `payload`。
-7. 输出格式默认优先 `--format pretty`（时间线更易读，并带当前身份标签）；需要稳定字段做结构化处理时用 `--format json`；需要流式消费事件时用 `--format ndjson`。
-8. **必须识别分页信号**：只要响应里出现 `has_more=true`、pretty 里的 `more available`，或返回了非空 `page_token`，就不能把当前结果当作完整事件流；默认应继续分页，或明确告诉用户当前只是部分结果。
-9. 保留响应里的 `page_token`，下次增量拉取直接续，不要从头再拉。
-10. **只要你是基于** **`+meeting-events`** **来回答一场正在进行中的会议内容，就不能直接复用旧结果。** 无论用户是在问“现在/刚刚/最新”的状态，还是让你“总结一下这个会议讲什么”，都必须先重新拉一次当前事件流，确认拿到的是最新信息，再基于最新结果回答。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。
-11. **会中聊天 / 互动转发到 IM 时基于 JSON 事件构造 IM post。** `chat_received_items[].message_type == 3` 表示会中 reaction；构造 IM post 时，先用 [`lark-im` reaction emoji 白名单](../lark-im/references/lark-im-reactions.md) 判断同一 item 的 `content`：白名单内才写成 Feishu post `emotion` 节点，不在白名单内则保留原始 key 并写成文本节点，例如 `[CanNotSee]`。普通聊天按文本发送。不要从 pretty/Markdown 重新拼消息，也不要把整条消息退化成纯文本；只降级非法 reaction key。用户已说“发给我 / 推送给我 / 发到我的单聊”时，默认用 bot 身份直接发当前用户；收件人不明确时只补问收件人。
-12. 用户直接问“这个会议讲了什么 / 现在讲到哪了”且上下文没有明确 `meeting_id` 时，先用用户身份发现当前会议；如果用户明确要求应用机器人视角，或上下文已经是应用机器人参会流程，再用应用身份发现。若返回多个会议，展示候选并让用户选择。
-13. 用户直接提供 **9 位会议号** 并询问会中事件/会议内容时，默认把它当作 active meeting 的筛选条件：先按当前身份查 active meetings，并在返回里匹配 `meeting_no == <9位会议号>`；匹配到唯一会议后取长数字 `meeting_id`，再用同一身份查事件。只有用户明确要求“入会 / 让应用机器人旁听 / 代我参会”时才改用 `+meeting-join`。
+6. 输出格式默认优先 `--format pretty`（时间线更易读）；只有在需要完整保留原始消息流与结构化字段时，才使用 `--format json`。
+7. **必须识别分页信号**：只要响应里出现 `has_more=true`、pretty 里的 `more available`，或返回了非空 `page_token`，就不能把当前结果当作完整事件流；默认应继续分页，或明确告诉用户当前只是部分结果。
+8. 保留响应里的 `page_token`，下次增量拉取直接续，不要从头再拉。
+9. **只要你是基于** **`+meeting-events`** **来回答一场正在进行中的会议内容，就不能直接复用旧结果。** 无论用户是在问“现在/刚刚/最新”的状态，还是让你“总结一下这个会议讲什么”，都必须先重新拉一次当前事件流，确认拿到的是最新信息，再基于最新结果回答。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。
+10. 用户直接问“这个会议讲了什么 / 现在讲到哪了”且上下文没有明确 `meeting_id` 时，先用用户身份发现当前会议；如果用户明确要求应用机器人视角，或上下文已经是应用机器人参会流程，再用应用身份发现。若返回多个会议，展示候选并让用户选择。
+11. 用户直接提供 **9 位会议号** 并询问会中事件/会议内容时，默认把它当作 active meeting 的筛选条件：先按当前身份查 active meetings，并在返回里匹配 `meeting_no == <9位会议号>`；匹配到唯一会议后取长数字 `meeting_id`，再用同一身份查事件。只有用户明确要求“入会 / 让应用机器人旁听 / 代我参会”时才改用 `+meeting-join`。
 
 ### 3. 发送会中文本或会中表情（写操作）
 
@@ -121,14 +119,13 @@ lark-cli vc +meeting-message-send --as bot --meeting-id <meeting_id> --msg-type
 
 ```bash
 # 1. 入会，捕获 meeting.id
-AS=bot
-JOIN=$(lark-cli vc +meeting-join --as "$AS" --meeting-number 123456789 --format json)
+JOIN=$(lark-cli vc +meeting-join --as bot --meeting-number 123456789 --format json)
 MID=$(echo "$JOIN" | jq -r '.data.meeting.id')
 
 # 2. 会中轮询事件
-#    沿用入会身份；默认用 --page-all 拉全当前可见事件；下次增量优先复用 page_token
+#    默认用 --page-all 拉全当前可见事件；下次增量优先复用 page_token
 #    典型间隔 10-30 秒
-lark-cli vc +meeting-events --as "$AS" --meeting-id "$MID" --page-all --format pretty
+lark-cli vc +meeting-events --as bot --meeting-id "$MID" --page-all --format pretty
 
 # 3. 会后可选：进入 lark-vc 获取会议产物信息，再按 note_id / minute_token 决策读取
 lark-cli vc +detail --meeting-ids "$MID"
@@ -140,7 +137,7 @@ lark-cli vc +detail --meeting-ids "$MID"
 
 ```bash
 lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
-lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
+lark-cli vc +meeting-events --as bot --meeting-id <meeting_id> --page-all --format pretty
 ```
 
 如果只是回答当前登录用户所在会议发生了什么，使用用户身份一路查：

skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md

@@ -14,14 +14,17 @@
 ## 命令
 
 ```bash
-# 默认用法：全量拉取当前身份可见事件；输出易读时间线
-lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format pretty
+# 默认用法：全量拉取当前可见事件
+lark-cli vc +meeting-events --as <same_identity> --meeting-id 69xxxxxxxxxxxxx28 --page-all --format pretty
 
 # 指定时间范围，并拉全该时间窗内当前可见事件
-lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --start 2026-04-17T15:00:00+08:00 --end 2026-04-17T16:00:00+08:00 --page-all --format pretty
+lark-cli vc +meeting-events --as <same_identity> --meeting-id 69xxxxxxxxxxxxx28 --start 2026-04-17T15:00:00+08:00 --end 2026-04-17T16:00:00+08:00 --page-all --format pretty
 
 # 基于上一次保存的 page_token 继续查新增事件
-lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token <last_page_token> --page-all --format pretty
+lark-cli vc +meeting-events --as <same_identity> --meeting-id 69xxxxxxxxxxxxx28 --page-token <last_page_token> --page-all --format pretty
+
+# 调试或控制返回体大小时，显式只查一页
+lark-cli vc +meeting-events --as <same_identity> --meeting-id 69xxxxxxxxxxxxx28 --page-size 20 --format json
 ```
 
 ## 参数
@@ -51,10 +54,9 @@ lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token
 
 ### 2. 身份来源是读取事件的权限锚点
 
-- `+meeting-events` 支持 `--as user` 和 `--as bot`。
-- 用户身份路径：用户身份发现的会议继续用用户身份读取。
-- 应用身份路径：应用机器人必须在会中或参会过；不要拿任意 `meeting_id` 直接查。
-- 不要在拿到 `meeting_id` 后随意切换身份。身份不一致时，常见结果是空列表、`no permission` 或 `bot is not in meeting`。
+- 用户身份路径：先用 `+meeting-list-active --as user` 发现当前登录用户的会议，再用 `+meeting-events --as user` 读取该 `meeting_id`。
+- 应用身份路径：应用机器人必须在会中或参会过；不要拿任意 `meeting_id` 直接用 `--as bot` 查。
+- 不要混用身份。身份不一致时，常见结果是空列表、`no permission` 或 `bot is not in meeting`。
 
 ### 3. 读取事件前必须先拿到可见的 meeting_id
 
@@ -65,21 +67,21 @@ lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token
 lark-cli vc +meeting-join --as bot --meeting-number 123456789
 
 # 再查询事件
-lark-cli vc +meeting-events --as bot --meeting-id <id>
+lark-cli vc +meeting-events --as bot --meeting-id <meeting.id>
 ```
 
 如果应用机器人已经在会中，也可以先通过 active meeting 找会：
 
 ```bash
 lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
-lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
+lark-cli vc +meeting-events --as bot --meeting-id <meeting_id> --page-all --format pretty
 ```
 
-如果要查询当前登录用户所在会议：
+如果只是查询当前登录用户所在会议：
 
 ```bash
 lark-cli vc +meeting-list-active --as user --format json
-lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pretty
+lark-cli vc +meeting-events --as user --meeting-id <meeting_id> --page-all --format pretty
 ```
 
 若应用机器人已离会、未入会、或会议已经无法再判断身份，后端通常会报：
@@ -102,19 +104,18 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 
 执行准则：
 
-- **默认命令模板**：`lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format pretty`
+- **默认命令模板**：`lark-cli vc +meeting-events --as <same_identity> --meeting-id <meeting.id> --page-all --format pretty`
 - 如果你发现自己执行成了不带 `--page-all` 的单页查询，而响应里又出现 `has_more=true` / `more available` / 非空 `page_token`，应立刻意识到这只是部分结果。
-- 遇到上述情况，默认补救方式是继续使用返回的 `page_token` 续拉，例如：`lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token <returned_page_token> --page-all --format pretty`
+- 遇到上述情况，默认补救方式是继续使用返回的 `page_token` 续拉，例如：`lark-cli vc +meeting-events --as <same_identity> --meeting-id <meeting.id> --page-token <returned_page_token> --page-all --format pretty`
 - 只有在用户明确要求“就看第一页”“先不要翻页”时，才不要默认带 `--page-all`
 - 只要你是基于 `+meeting-events` 来回答一场**正在进行中的会议内容**，就不能直接复用上一次查询结果。无论用户是在问“现在是谁在说话”“刚刚发生了什么”“最新事件有哪些”，还是让你“总结一下这个会议讲什么”，都必须先重新执行一次 `+meeting-events`，确认拿到的是最新事件流，再回答用户。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。
 
-### 5. 输出格式差异
+### 5. pretty / json 输出差异
 
-- `--format json`：结构化契约，顶层包含 `meeting`、`identity`、`events`、`has_more`、`page_token`。`identity` 表示当前读取身份；事件 actor 统一含 `participant_type`、`role`、`label`；每条事件保留 `payload` 便于追溯细节。
-- `--format pretty`：默认推荐格式，输出当前身份和逐条时间线，适合快速理解“发生了什么”。
-- `--format ndjson`：输出事件行，并带 metadata 行，适合流式消费。
+- `--format pretty`：输出会议主题、会议时间和逐条时间线，适合快速理解“发生了什么”，也是本 skill 的默认推荐格式。
+- `--format json`：保留完整原始 `events[]` 结构——参会人 open_id、聊天原文、share_doc、分页字段都在原始响应里，适合提取字段、联动其他命令或做进一步程序处理。
 
-**选型原则**：只在 `pretty`、`json`、`ndjson` 之间选择。目标是告诉用户“发生了什么”时，用 `--page-all --format pretty`；需要稳定字段给 agent 做结构化消费、总结、转发或二次处理时用 `--format json`；需要流式消费时用 `--format ndjson`。
+**选型原则**：只要目标是告诉用户“发生了什么”，默认就用 `--page-all --format pretty`；只有在需要完整原始消息流和结构化字段时，才改用 `json`。
 
 > **注意**：pretty 输出中的正文文本会做单行转义，真实换行会显示为 `\n`，避免打乱时间线布局。
 
@@ -131,10 +132,10 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 
 执行准则：
 
-- 如果上下文已有明确 `meeting_id`，沿用该 `meeting_id` 的来源身份执行 `+meeting-events --page-all --format json`。
-- 如果上下文没有明确 `meeting_id`，先按用户当前意图选择身份：问“我/当前用户所在会议”用 `lark-cli vc +meeting-list-active --as user --format json`；问“应用机器人可见的目标用户会议”用 `lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json`。返回多个会议时先让用户选择。
+- 如果上下文已有明确 `meeting_id` 和来源身份，直接用同一身份执行 `+meeting-events --page-all --format json`。
+- 如果上下文没有明确 `meeting_id`，先按用户当前意图选择身份：问“我/当前用户所在会议”用 `lark-cli vc +meeting-list-active --as user --format pretty`；问“应用机器人可见的目标用户会议”用 `lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format pretty`。返回多个会议时先让用户选择。
 - 如果上下文只有 9 位会议号，先按当前身份执行 `+meeting-list-active` 并按 `meeting_no` 匹配；匹配到唯一会议后再查事件。不要为了总结会议而自动调用 `+meeting-join`。
-- 这类问题拿到 `meeting_id` 后，用同一身份执行 `lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format json` 拉取最新事件流。
+- 这类问题拿到 `meeting_id` 后，用 `lark-cli vc +meeting-events --as <same_identity> --meeting-id <meeting.id> --page-all --format json` 拉取最新事件流。
 - 如果事件中出现共享文档线索，例如：
   - `magic_share_started`
   - `share_doc.title`
@@ -158,10 +159,7 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 
 | 字段 | 说明 |
 |------|------|
-| `meeting` | 会议身份与时间状态，包含 `id/topic/meeting_no/start_time/end_time/status` |
-| `identity` | 当前读取身份，包含 `id/name/participant_type/label` |
-| `events` | 结构化事件列表；每条事件含参与者 `actors` 和事件细节 `payload` |
-| `warnings` | 非阻断告警列表；事件列表本身仍可使用 |
+| `events` | 事件列表 |
 | `has_more` | 是否还有下一页 |
 | `page_token` | 下一页游标 |
 
@@ -176,32 +174,6 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 | `magic_share_started` | 开始共享内容 / 文档 |
 | `magic_share_ended` | 结束共享 |
 
-### Forwarding meeting chat and reactions to IM
-
-转发到 IM 时，Agent 必须先用 `+meeting-events --format json` 的结构化事件构造完整 Feishu `post` 内容，再调用 IM 发送 shortcut。不要解析 pretty/Markdown 输出，也不要先生成纯文本或 Markdown 后再期望 IM 侧二次识别 reaction。
-
-对 `event_type == "chat_received"` 的事件逐项处理 `payload.chat_received_items`：
-
-- `message_type == 3` 是会中 reaction；构造 IM `post` 内容时，以 [`lark-im` reaction emoji 列表](../../lark-im/references/lark-im-reactions.md) 作为 IM `emotion` 白名单。白名单内的 key 写成 `{"tag":"emotion","emoji_type":"<content>"}`，例如 `JIAYI`、`THUMBSUP`、`OK`。
-- 对不在 IM reaction emoji 白名单内的 reaction key，保留原始 key 但写成文本节点，例如 `{"tag":"text","text":"[<content>]"}`；不应直接写入 `emotion.emoji_type`，否则 IM 发送会失败。
-- 不要大小写归一化或猜测映射；`content` 是原始 reaction key，必须原样判断。
-- 其他聊天消息写成文本节点：`{"tag":"text","text":"<content>"}`。
-- 最终调用 `im +messages-send --msg-type post --content '<post-json>'`，其中 `<post-json>` 应混合使用可渲染 `emotion` 节点和文本 fallback；不要用 `--markdown` 承载会中 reaction。
-- 如果 IM 返回 `message_content_emotion_tag's emoji_type is invalid`，只降级非法 reaction key，不要把整条消息退化成纯文本。
-- 如果用户原始请求已经明确“发给我 / 推送给我 / 发到我的聊天框 / 发到我的单聊”，这已经覆盖本次收件人、内容和发送动作，直接发送给当前用户，不要再二次询问“是否发送”。
-- 默认用应用身份 `--as bot` 发送；只有用户明确要求“用本人身份 / 用户身份发送”时才切到 `--as user`。
-- 如果用户要求发给某个群或其他人但收件人不可唯一确定，只询问缺失的收件人信息。
-
-```bash
-lark-cli vc +meeting-events \
-  --as <same_identity> \
-  --meeting-id <id> \
-  --page-all \
-  --format json
-```
-
-如果用户已经要求“发给我”，`<open_id>` 使用当前用户的 open_id；需要解析时先用用户查询能力获取当前用户信息。构造 IM post 时只发送用户请求范围内的会中内容，不要把前一条自然语言预览当作发送内容。
-
 ## pretty 输出示例
 
 ```text
@@ -225,29 +197,28 @@ lark-cli vc +meeting-events \
 
 ## Agent 组合场景
 
-### 场景 1：入会后读取会中发生了什么
+### 场景 1：入会后查看会中发生了什么
 
 ```bash
 # 第 1 步：加入会议，记录返回的 meeting.id
-JOIN=$(lark-cli vc +meeting-join --as bot --meeting-number 123456789 --format json)
-MID=$(echo "$JOIN" | jq -r '.data.meeting.id')
+lark-cli vc +meeting-join --as bot --meeting-number 123456789
 
-# 第 2 步：用 meeting.id 读取当前可见事件
-lark-cli vc +meeting-events --as bot --meeting-id "$MID" --page-all --format pretty
+# 第 2 步：查询事件流
+lark-cli vc +meeting-events --as bot --meeting-id <meeting.id> --page-all --format pretty
 ```
 
 ### 场景 1b：应用机器人已在会中，先发现 meeting_id 再读事件
 
 ```bash
 lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
-lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
+lark-cli vc +meeting-events --as bot --meeting-id <meeting_id> --page-all --format pretty
 ```
 
 ### 场景 1c：当前登录用户正在会中，先发现 meeting_id 再读事件
 
 ```bash
 lark-cli vc +meeting-list-active --as user --format json
-lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pretty
+lark-cli vc +meeting-events --as user --meeting-id <meeting_id> --page-all --format pretty
 ```
 
 ### 场景 2：过滤某段时间内的事件
@@ -255,7 +226,7 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pret
 ```bash
 lark-cli vc +meeting-events \
   --as <same_identity> \
-  --meeting-id <id> \
+  --meeting-id <meeting.id> \
   --start 2026-04-17T15:00:00+08:00 \
   --end 2026-04-17T16:00:00+08:00 \
   --page-all \
@@ -269,7 +240,7 @@ lark-cli vc +meeting-events \
 # 这次直接从该游标继续拉新增事件
 lark-cli vc +meeting-events \
   --as <same_identity> \
-  --meeting-id <id> \
+  --meeting-id <meeting.id> \
   --page-token <last_page_token> \
   --page-all \
   --format pretty
@@ -286,9 +257,10 @@ lark-cli vc +meeting-events \
 | 错误现象 | 根本原因 | 解决方案 |
 |---------|---------|---------|
 | `--meeting-id is required` | 未传入 `--meeting-id` | 传入长数字 `meeting.id` |
-| `10005 bot is not in meeting` | 使用应用身份读取，但应用机器人从未真实入会该会议；或会议已结束但应用机器人从未在会中出现过 | 如果 `meeting_id` 来自用户身份发现，改回 `--as user`；如果确实要应用身份读取，先让应用机器人入会或确认它曾参会后再用 `--as bot`。**如果只是想看参会人快照，改用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants`** |
-| 用户身份无权限 / 不可见 | 当前用户不是该会议的可见参与者，或 `meeting_id` 不是从用户身份路径获得 | 不要反复执行 `auth login`。先确认 `meeting_id` 是否来自 `+meeting-list-active --as user`；如果用户明确要切到应用身份，再通过 `+meeting-list-active --as bot --user-id <user_open_id>` 获取应用身份可读的 `meeting_id`，或在用户明确同意后让应用机器人入会，再用 `+meeting-events --as bot` 读取 |
-| `20001 meeting_status_MEETING_END` | 会议已结束且已超出后端允许的 5 分钟宽限窗口 | 本接口不再适合继续拉取事件。先用 `lark-cli vc +detail --meeting-ids <meeting.id>` 获取会议产物信息，再根据 `note_display_type` / `note_id` / `minute_token` 和用户意图选择纪要正文、逐字稿或妙记；参会人请用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants` |
+| `not a 9-digit meeting number` | 把 9 位会议号误传给 `--meeting-id` | 如果只是查询会中内容，先用 `+meeting-list-active` 按 `meeting_no` 匹配拿长数字 `meeting_id`；只有用户明确要求入会时才用 `+meeting-join --as bot --meeting-number <9位号>` |
+| `10005 bot is not in meeting` | 使用应用身份读取，但应用机器人从未真实入会该会议；或会议已结束但应用机器人从未在会中出现过 | 如果本来是用户身份发现的 `meeting_id`，改回 `--as user`；如果确实要应用身份读取，先 `+meeting-join --as bot --meeting-number <9位号>` 真实入会再查。**如果只是想看参会人快照，改用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants`** |
+| 用户身份不支持 | 当前事件读取接口不支持用用户身份访问 | 不要反复执行 `auth login`。改用应用身份流程：先通过 `+meeting-list-active --as bot --user-id <user_open_id>` 获取应用身份可读的 `meeting_id`，或在用户明确同意后让应用机器人入会，再用 `+meeting-events --as bot` 读取 |
+| `20001 meeting_status_MEETING_END` | 会议已结束且已超出后端允许的 5 分钟宽限窗口 | 本接口不再适合继续拉取事件。先用 `lark-cli vc +detail --meeting-ids <meeting.id>` 获取会议产物信息，再根据 `note_id` / `minute_token` 和用户意图选择纪要正文、逐字稿或妙记；参会人请用 `lark-cli vc meeting get --params '{"meeting_id":"<meeting.id>"}' --with-participants` |
 | `20002 meeting not exist` | `meeting_id` 错误，或会议实例当前已不可获取（常见于把 9 位会议号当 meeting_id 传） | 确认传入的是长数字 `meeting_id`，不是 9 位会议号 |
 | 应用身份权限不足 | 应用权限、租户安装、权限可访问的数据范围或 VC Agent privilege 未配置完整 | 不要执行 `auth login`。以 CLI 返回的 metadata / error envelope 为准确认缺失权限；检查应用发布/安装，以及开放平台“权限可访问的数据范围”：选择“按条件筛选”，条件为“会议的归属者 包含 与应用的可用范围一致”；仍失败再排查内测 privilege / 灰度 |
 | `HTTP 404` / `HTTP 500` | 服务端当前无法找到或处理该会议实例 | 换一个正在进行且 bot 可见的 meeting_id，或排查后端问题 |

skills/lark-vc-agent/references/lark-vc-agent-meeting-list-active.md

@@ -29,7 +29,7 @@ lark-cli vc +meeting-list-active --as bot --user-id ou_xxx --format json
 | 用户身份 | `--as user` | 当前登录用户正在参加的会议 | 继续 `+meeting-events --as user` |
 | 应用身份 | `--as bot --user-id <user_open_id>` | 目标用户正在参加、且应用机器人也在会中的会议 | 继续 `+meeting-events --as bot` |
 
-硬规则：`meeting_id` 从哪种身份路径拿到，后续 `+meeting-events` 就沿用哪种身份。不要把应用身份拿到的 `meeting_id` 改用用户身份读事件，也不要把用户身份拿到的 `meeting_id` 强制切到应用身份。
+硬规则：`meeting_id` 从哪种身份路径拿到，后续 `+meeting-events` 就沿用哪种身份。不要把用户身份拿到的 `meeting_id` 改用应用身份查，也不要把应用身份拿到的 `meeting_id` 改用用户身份查，除非用户明确要求切换场景。
 
 应用身份返回空，不代表目标用户不在任何会议中，只能说明没有找到“目标用户在会中且应用机器人也在会中”的当前会。
 
@@ -38,22 +38,22 @@ lark-cli vc +meeting-list-active --as bot --user-id ou_xxx --format json
 ```bash
 # 方式 1：先让应用机器人入会，直接从 join 响应拿 meeting.id
 lark-cli vc +meeting-join --as bot --meeting-number 123456789 --format json
-lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
+lark-cli vc +meeting-events --as bot --meeting-id <meeting.id> --page-all --format pretty
 
 # 方式 2：应用机器人已经在会中时，用应用身份发现 meeting_id
 lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
-lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
+lark-cli vc +meeting-events --as bot --meeting-id <meeting_id> --page-all --format pretty
 
-# 方式 3：查询当前登录用户所在会议发生了什么
+# 方式 3：只回答当前登录用户所在会议发生了什么
 lark-cli vc +meeting-list-active --as user --format json
-lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pretty
+lark-cli vc +meeting-events --as user --meeting-id <meeting_id> --page-all --format pretty
 ```
 
 ## 多会议选择
 
 - 如果返回多个会议，不要自动挑第一个。
 - 向用户展示每个候选的 `meeting_title` / `meeting_no` / `meeting_id`，等待用户选择。
-- 选择后用同一身份执行 `+meeting-events` 读取事件。
+- 选择后继续使用发现该会议时的同一身份调用 `+meeting-events`。
 
 ## 9 位会议号匹配
 
@@ -80,7 +80,7 @@ lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
 |---------|---------|---------|
 | `--user-id is required when --as bot` | 应用身份未传目标用户 | 传入目标用户 open_id |
 | 用户身份返回空列表 | 当前登录用户没有可见的进行中会议 | 确认用户是否在会中，或是否切错身份 |
-| 用户身份无权限 / 不可见 | 当前登录用户没有可见的进行中会议，或当前身份无法读取该会议 | 不要反复执行 `auth login`。先确认当前登录用户是否在会中、是否切错 profile；如果用户明确要查询应用机器人可见的会议，再拿目标用户 open_id 执行 `+meeting-list-active --as bot --user-id <user_open_id>`，并按应用身份权限配置检查应用权限、安装、数据范围和灰度 |
+| 用户身份不支持 | 当前接口不支持用用户身份访问 | 不要反复执行 `auth login`。改用应用身份流程：先拿目标用户 open_id，再执行 `+meeting-list-active --as bot --user-id <user_open_id>`；同时按应用身份权限配置检查应用权限、安装、数据范围和灰度 |
 | 应用身份返回空列表 | 没有满足“目标用户在会中且应用机器人也在会中”的当前会 | 先让应用机器人入会，或确认 `user_id` 和会议状态 |
 | `--user-id` 格式错误 | 传入了 internal user_id 或其他非 `ou_...` 值 | 改传目标用户 open_id |
 | 应用身份权限不足 | 应用权限、租户安装、权限可访问的数据范围或 VC Agent privilege 未配置完整 | 不要执行 `auth login`。以 CLI 返回的 metadata / error envelope 为准确认缺失权限；检查应用发布/安装，以及开放平台“权限可访问的数据范围”：选择“按条件筛选”，条件为“会议的归属者 包含 与应用的可用范围一致”；仍失败再排查内测 privilege / 灰度 |

skills/lark-wiki/references/lark-wiki-node-get.md

@@ -19,7 +19,7 @@ lark-cli wiki +node-get \
 |------|------|----------|---------|-------------|
 | `--node-token` | string | **Yes** | — | `node_token`, cloud-doc `obj_token`, or a Lark URL embedding one (e.g. `https://feishu.cn/wiki/<token>` or `https://feishu.cn/docx/<token>`). Matches the `--node-token` naming used by sibling `+node-delete` / `+node-copy` / `+move`. |
 | `--token` | string | — (deprecated) | — | Deprecated original name; still accepted for backward compatibility but emits a `Flag --token has been deprecated, use --node-token instead` warning on stderr. New scripts should use `--node-token`. |
-| `--obj-type` | enum | No | — | Needed when `--node-token` is a raw `obj_token`; auto-inferred from typed Lark URLs. If omitted for a raw token, the shortcut treats it as a wiki `node_token`. |
+| `--obj-type` | enum | No | — | Needed when `--node-token` is a raw `obj_token`; auto-inferred from the URL path. Not allowed when the token looks like a `node_token` (`wik...`) |
 | `--space-id` | string | No | — | Optional cross-check: fail if the resolved node does not live in this space |
 | `--format` | enum | No | `json` | `json` / `pretty` / `table` / `csv` / `ndjson` |
 | `--as` | enum | No | `auto` | Identity `user`/`bot`; wiki is user-centric → pass `--as user` |

tests/cli_e2e/apps/apps_db_execute_dryrun_test.go

@@ -15,11 +15,11 @@ import (
 )
 
 // TestAppsDBExecuteDryRun pins +db-execute 复用存量 URL，CLI 永远走 DBA 模式
-// （?transactional=false），sql body 由 --sql 透传，默认不传 env（空值，由服务端按 workspace 定分支）。
+// （?transactional=false），sql body 由 --sql 透传，默认 env=dev。
 func TestAppsDBExecuteDryRun(t *testing.T) {
 	setAppsDryRunEnv(t)
 
-	t.Run("DefaultEnvUnsetAndTransactionalFalse", func(t *testing.T) {
+	t.Run("DefaultEnvIsDevAndTransactionalFalse", func(t *testing.T) {
 		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 		t.Cleanup(cancel)
 
@@ -37,8 +37,8 @@ func TestAppsDBExecuteDryRun(t *testing.T) {
 			"CLI is DBA mode → must send transactional=false in query")
 		assert.False(t, gjson.Get(result.Stdout, "api.0.body.transactional").Exists(),
 			"transactional should be in query, not body")
-		assert.False(t, gjson.Get(result.Stdout, "api.0.params.env").Exists(),
-			"default: no --environment → env key must be omitted (server picks workspace default branch)")
+		assert.Equal(t, "dev", gjson.Get(result.Stdout, "api.0.params.env").String(),
+			"default env must be dev (not production)")
 	})
 
 	t.Run("OnlineEnvSwitch", func(t *testing.T) {

tests/cli_e2e/apps/apps_db_table_list_dryrun_test.go

@@ -19,7 +19,7 @@ import (
 func TestAppsDBTableListDryRun(t *testing.T) {
 	setAppsDryRunEnv(t)
 
-	t.Run("DefaultsToNoEnvAndPageSize20", func(t *testing.T) {
+	t.Run("DefaultsToDevAndPageSize20", func(t *testing.T) {
 		ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 		t.Cleanup(cancel)
 
@@ -32,8 +32,7 @@ func TestAppsDBTableListDryRun(t *testing.T) {
 
 		assert.Equal(t, "GET", gjson.Get(result.Stdout, "api.0.method").String())
 		assert.Equal(t, "/open-apis/spark/v1/apps/app_x/tables", gjson.Get(result.Stdout, "api.0.url").String())
-		assert.False(t, gjson.Get(result.Stdout, "api.0.params.env").Exists(),
-			"default: no --environment → env key must be omitted (server picks workspace default branch)")
+		assert.Equal(t, "dev", gjson.Get(result.Stdout, "api.0.params.env").String())
 		assert.Equal(t, "20", gjson.Get(result.Stdout, "api.0.params.page_size").String())
 		assert.False(t, gjson.Get(result.Stdout, "api.0.params.page_token").Exists(),
 			"empty page_token must be omitted")

tests/cli_e2e/vc/vc_meeting_events_dryrun_test.go

@@ -1,46 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package vc
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	clie2e "github.com/larksuite/cli/tests/cli_e2e"
-	"github.com/stretchr/testify/require"
-	"github.com/tidwall/gjson"
-)
-
-func TestVCMeetingEventsDryRun(t *testing.T) {
-	setVCDryRunEnv(t)
-
-	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
-	t.Cleanup(cancel)
-
-	result, err := clie2e.RunCmd(ctx, clie2e.Request{
-		Args: []string{
-			"vc", "+meeting-events",
-			"--meeting-id", "7628568141510692381",
-			"--page-token", "1710000000000000000",
-			"--page-size", "40",
-			"--start", "1710000000",
-			"--end", "1710003600",
-			"--dry-run",
-		},
-		DefaultAs: "bot",
-	})
-	require.NoError(t, err)
-	result.AssertExitCode(t, 0)
-
-	out := result.Stdout
-	require.Equal(t, int64(1), gjson.Get(out, "api.#").Int(), "stdout:\n%s", out)
-	require.Equal(t, "GET", gjson.Get(out, "api.0.method").String(), "stdout:\n%s", out)
-	require.Equal(t, "/open-apis/vc/v1/bots/events", gjson.Get(out, "api.0.url").String(), "stdout:\n%s", out)
-	require.Equal(t, "7628568141510692381", gjson.Get(out, "api.0.params.meeting_id").String(), "stdout:\n%s", out)
-	require.Equal(t, "1710000000000000000", gjson.Get(out, "api.0.params.page_token").String(), "stdout:\n%s", out)
-	require.Equal(t, "40", gjson.Get(out, "api.0.params.page_size").String(), "stdout:\n%s", out)
-	require.Equal(t, "1710000000", gjson.Get(out, "api.0.params.start_time").String(), "stdout:\n%s", out)
-	require.Equal(t, "1710003600", gjson.Get(out, "api.0.params.end_time").String(), "stdout:\n%s", out)
-}

tests/cli_e2e/vc/vc_meeting_message_send_dryrun_test.go

@@ -15,7 +15,7 @@ import (
 )
 
 func TestVCMeetingMessageSendDryRun(t *testing.T) {
-	setVCDryRunEnv(t)
+	setVCMeetingMessageSendDryRunEnv(t)
 
 	tests := []struct {
 		name        string
@@ -81,7 +81,7 @@ func TestVCMeetingMessageSendDryRun(t *testing.T) {
 }
 
 func TestVCMeetingMessageSendDryRunRejectsLongUUID(t *testing.T) {
-	setVCDryRunEnv(t)
+	setVCMeetingMessageSendDryRunEnv(t)
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
 	t.Cleanup(cancel)
 
@@ -104,10 +104,10 @@ func TestVCMeetingMessageSendDryRunRejectsLongUUID(t *testing.T) {
 	require.Empty(t, result.Stdout)
 }
 
-func setVCDryRunEnv(t *testing.T) {
+func setVCMeetingMessageSendDryRunEnv(t *testing.T) {
 	t.Helper()
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	t.Setenv("LARKSUITE_CLI_APP_ID", "vc_dryrun_test")
-	t.Setenv("LARKSUITE_CLI_APP_SECRET", "vc_dryrun_secret")
+	t.Setenv("LARKSUITE_CLI_APP_ID", "vc_meeting_message_send_dryrun_test")
+	t.Setenv("LARKSUITE_CLI_APP_SECRET", "vc_meeting_message_send_dryrun_secret")
 	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
 }