chore: import upstream snapshot with attribution

cmd/service/affordance.go

@@ -0,0 +1,336 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"encoding/json"
+	"fmt"
+	"io/fs"
+	"strings"
+
+	"github.com/larksuite/cli/internal/affordance"
+	"github.com/larksuite/cli/internal/cmdmeta"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/meta"
+	"github.com/spf13/cobra"
+)
+
+// PrepareDomainHelp appends navigational guidance (routing line, risk legend,
+// skill pointer) to a top-level Lark domain's description, returning false for
+// anything that is not such a domain. Built lazily at help time because
+// shortcuts attach after service registration. skillFS (nil-safe) gates the
+// skill pointer.
+//
+// A hand-authored Long is preserved as the base (e.g. event's "Use 'event
+// consume <EventKey>'…"); service domains carry only a Short at this point, so
+// we fall back to it. The pristine base is captured once into an annotation so
+// re-rendering does not append the guidance twice.
+func PrepareDomainHelp(cmd *cobra.Command, skillFS fs.FS) bool {
+	if cmd.Annotations[schemaPathAnnotation] != "" {
+		return false // a method command
+	}
+	// Direct child of root only — so Domain() reads this command's own tag, and
+	// nested resource groups are excluded.
+	if cmd.Parent() == nil || cmd.Parent().Parent() != nil {
+		return false
+	}
+	// A domain is service-sourced or shortcut-tagged; CLI tooling has neither.
+	if src, _ := cmdmeta.SourceOf(cmd); src != cmdmeta.SourceService && cmdmeta.Domain(cmd) == "" {
+		return false
+	}
+	if !cmd.HasAvailableSubCommands() {
+		return false
+	}
+
+	hasShortcuts, hasResources := false, false
+	for _, c := range cmd.Commands() {
+		if c.Hidden || c.Name() == "help" || c.Name() == "completion" {
+			continue
+		}
+		if strings.HasPrefix(c.Name(), "+") {
+			hasShortcuts = true
+		} else {
+			hasResources = true
+		}
+	}
+
+	var b strings.Builder
+	b.WriteString(domainHelpBase(cmd))
+	if hasShortcuts && hasResources { // routing only matters when both styles exist
+		b.WriteString("\n\nPrefer a +-prefixed shortcut when one matches your task; otherwise use the raw API resource below.")
+	}
+	b.WriteString("\n\nRisk levels (read | write | high-risk-write) appear in each command's --help; high-risk-write requires --yes, only after the user confirms.")
+	if skill := "lark-" + cmd.Name(); skillFS != nil {
+		if _, err := fs.Stat(skillFS, skill+"/SKILL.md"); err == nil {
+			fmt.Fprintf(&b, "\n\nDomain guide (concepts, command choice, conventions): lark-cli skills read %s", skill)
+		}
+	}
+	cmd.Long = b.String()
+	return true
+}
+
+// domainHelpBase returns the description to seed domain help with — the
+// hand-authored Long when present, else the Short.
+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 {
+		return base
+	}
+	base := cmd.Long
+	if base == "" {
+		base = cmd.Short
+	}
+	if cmd.Annotations == nil {
+		cmd.Annotations = map[string]string{}
+	}
+	cmd.Annotations[key] = base
+	return base
+}
+
+// methodLong is the build-time Long (description + schema pointer +
+// params-only addendum). Agent guidance is added lazily by PrepareMethodHelp,
+// so command construction never parses the overlay.
+func methodLong(description, schemaPath, paramsOnly string) string {
+	var b strings.Builder
+	b.WriteString(description)
+	fmt.Fprintf(&b, "\n\nFull parameter schema:\n  lark-cli schema %s", schemaPath)
+	b.WriteString(paramsOnly)
+	return b.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"
+)
+
+// setMethodHelpData records the coordinates PrepareMethodHelp needs (storing a
+// few strings is the only build-time cost; the overlay stays untouched).
+func setMethodHelpData(cmd *cobra.Command, service, methodID, schemaPath, paramsOnly string) {
+	if cmd.Annotations == nil {
+		cmd.Annotations = map[string]string{}
+	}
+	cmdmeta.SetAffordanceRef(cmd, service, methodID)
+	cmd.Annotations[schemaPathAnnotation] = schemaPath
+	if paramsOnly != "" {
+		cmd.Annotations[paramsOnlyAnnotation] = paramsOnly
+	}
+}
+
+// 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 {
+	ann := cmd.Annotations
+	if ann == nil {
+		return false
+	}
+	schemaPath, ok := ann[schemaPathAnnotation]
+	if !ok {
+		return false
+	}
+
+	var b strings.Builder
+	b.WriteString(cmd.Short)
+	writeRisk(&b, cmd)
+
+	var skills []string
+	if raw, ok := affordanceRaw(cmd); ok {
+		if a, ok := (meta.Method{Affordance: raw}).ParsedAffordance(); ok {
+			if block := renderAffordanceValue(a); block != "" {
+				b.WriteString("\n\n")
+				b.WriteString(block)
+			}
+			skills = a.Skills
+		}
+	}
+
+	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(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)
+	}
+}
+
+// affordanceLookup is the overlay source; a package var so tests can inject.
+var affordanceLookup = affordance.For
+
+// RenderAffordanceForCmd renders a method command's affordance block, or "" when
+// it carries none.
+func RenderAffordanceForCmd(cmd *cobra.Command) string {
+	raw, ok := affordanceRaw(cmd)
+	if !ok {
+		return ""
+	}
+	return renderAffordance(meta.Method{Affordance: raw})
+}
+
+func affordanceRaw(cmd *cobra.Command) (json.RawMessage, bool) {
+	service, methodID, ok := cmdmeta.AffordanceRef(cmd)
+	if !ok {
+		return nil, false
+	}
+	return affordanceLookup(service, methodID)
+}
+
+// renderAffordance renders a method's affordance as a help block, or "" when it
+// has none. Sections are joined with blank lines so they scan as distinct groups.
+func renderAffordance(m meta.Method) string {
+	a, ok := m.ParsedAffordance()
+	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
+		for _, it := range items {
+			if strings.TrimSpace(it) != "" {
+				nonEmpty = append(nonEmpty, it)
+			}
+		}
+		if len(nonEmpty) == 0 {
+			return
+		}
+		var s strings.Builder
+		fmt.Fprintf(&s, "%s:\n", title)
+		for _, it := range nonEmpty {
+			fmt.Fprintf(&s, "  • %s\n", it)
+		}
+		sections = append(sections, strings.TrimRight(s.String(), "\n"))
+	}
+
+	bullets("When to use", a.UseWhen)
+	bullets("Avoid when", a.AvoidWhen)
+	bullets("Prerequisites", a.Prerequisites)
+	bullets("Tips", a.Tips)
+	if len(a.Examples) > 0 {
+		var lines []string
+		for _, ex := range a.Examples {
+			if ex.Command == "" {
+				continue
+			}
+			if ex.Description != "" {
+				lines = append(lines, fmt.Sprintf("  • %s\n      %s", ex.Description, ex.Command))
+			} else {
+				lines = append(lines, fmt.Sprintf("  • %s", ex.Command))
+			}
+		}
+		if len(lines) > 0 {
+			sections = append(sections, "Examples:\n"+strings.Join(lines, "\n"))
+		}
+	}
+	for _, ext := range a.Extensions {
+		bullets(ext.Label, ext.Items)
+	}
+	bullets("Related", a.Related)
+
+	return strings.Join(sections, "\n\n")
+}

cmd/service/affordance_test.go

@@ -0,0 +1,308 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+	"testing/fstest"
+
+	"github.com/larksuite/cli/internal/cmdmeta"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/meta"
+	"github.com/spf13/cobra"
+)
+
+func TestRenderAffordance(t *testing.T) {
+	raw := json.RawMessage(`{
+		"use_when": ["发送文本消息"],
+		"avoid_when": ["群已解散"],
+		"prerequisites": ["已获取 chat_id"],
+		"tips": ["富文本用 msg_type=post"],
+		"examples": [
+			{"description":"发一条文本","command":"lark-cli im messages create --params '{...}'"},
+			{"command":"lark-cli im messages list"},
+			{"description":"no command, skipped","command":""}
+		],
+		"related": ["im.messages.list"]
+	}`)
+	out := renderAffordance(meta.Method{Affordance: raw})
+	for _, want := range []string{
+		"When to use:", "发送文本消息",
+		"Avoid when:", "群已解散",
+		"Prerequisites:", "已获取 chat_id",
+		"Tips:", "富文本用 msg_type=post",
+		"Examples:", "发一条文本", "lark-cli im messages create --params '{...}'",
+		"lark-cli im messages list", // example with no description -> bare command line
+		"Related:", "im.messages.list",
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("renderAffordance missing %q in:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, "no command, skipped") {
+		t.Errorf("example with empty command should be skipped:\n%s", out)
+	}
+
+	// Absent or empty affordance renders nothing (so methods without an overlay
+	// add nothing to their help).
+	if renderAffordance(meta.Method{}) != "" || renderAffordance(meta.Method{Affordance: json.RawMessage(`{}`)}) != "" {
+		t.Error("empty affordance should render nothing")
+	}
+}
+
+// Affordance is rendered lazily (at --help time) rather than baked into the
+// command's Long, so building a command never carries the affordance block —
+// even for a method whose metadata happens to declare one.
+func TestServiceMethod_AffordanceNotInLong(t *testing.T) {
+	withAff := map[string]interface{}{
+		"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "发送消息",
+		"affordance": map[string]interface{}{
+			"examples": []interface{}{
+				map[string]interface{}{"description": "发文本", "command": "lark-cli im messages create ..."},
+			},
+		},
+	}
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(withAff), "create", "messages", nil)
+	if strings.Contains(cmd.Long, "Examples:") {
+		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)
+	}
+}
+
+// RenderAffordanceForCmd resolves a command's overlay through the (injectable)
+// lookup and renders it; commands without a ref render nothing.
+func TestRenderAffordanceForCmd(t *testing.T) {
+	orig := affordanceLookup
+	t.Cleanup(func() { affordanceLookup = orig })
+	affordanceLookup = func(service, methodID string) (json.RawMessage, bool) {
+		if service != "im" || methodID != "messages.create" {
+			return nil, false
+		}
+		return json.RawMessage(`{"use_when":["发文本消息"],"tips":["富文本用 msg_type=post"],"examples":[{"description":"发一条","command":"lark-cli im messages create ..."}]}`), true
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	withRef := map[string]interface{}{"id": "messages.create", "path": "messages", "httpMethod": "POST", "description": "发送消息"}
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(withRef), "create", "messages", nil)
+	block := RenderAffordanceForCmd(cmd)
+	for _, want := range []string{"When to use:", "发文本消息", "Tips:", "富文本用 msg_type=post", "Examples:", "lark-cli im messages create ..."} {
+		if !strings.Contains(block, want) {
+			t.Errorf("RenderAffordanceForCmd missing %q in:\n%s", want, block)
+		}
+	}
+
+	// No overlay for this method id -> empty block.
+	noRef := map[string]interface{}{"id": "x.list", "path": "x", "httpMethod": "GET", "description": "d"}
+	cmd2 := NewCmdServiceMethod(f, imSpec(), meta.FromMap(noRef), "list", "x", nil)
+	if got := RenderAffordanceForCmd(cmd2); got != "" {
+		t.Errorf("method with no overlay should render nothing, got:\n%s", got)
+	}
+}
+
+// PrepareMethodHelp composes the guidance into Long at the top: description,
+// then the affordance block, then the full-schema pointer — so an agent reads
+// when-to-use/examples before the flag list.
+func TestPrepareMethodHelp(t *testing.T) {
+	orig := affordanceLookup
+	t.Cleanup(func() { affordanceLookup = orig })
+	affordanceLookup = func(_, _ string) (json.RawMessage, bool) {
+		return json.RawMessage(`{"use_when":["发文本消息"],"examples":[{"description":"发一条","command":"lark-cli im messages create ..."}]}`), true
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	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) {
+		t.Fatal("PrepareMethodHelp returned false for a service-method command")
+	}
+	long := cmd.Long
+	// Description leads; affordance block sits above the schema pointer.
+	descAt := strings.Index(long, "发送消息")
+	useAt := strings.Index(long, "When to use:")
+	exAt := strings.Index(long, "Examples:")
+	schemaAt := strings.Index(long, "Full parameter schema:")
+	if descAt != 0 {
+		t.Errorf("description should lead Long, got:\n%s", long)
+	}
+	if !(descAt < useAt && useAt < exAt && exAt < schemaAt) {
+		t.Errorf("order should be description < affordance < schema pointer; got desc=%d use=%d ex=%d schema=%d\n%s", descAt, useAt, exAt, schemaAt, long)
+	}
+
+	// A non-service command (no schema-path annotation) is left untouched.
+	if PrepareMethodHelp(&cobra.Command{Use: "plain"}, nil) {
+		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 {
+	root := &cobra.Command{Use: "root"}
+	dom := &cobra.Command{Use: "event", Short: short, Long: long}
+	cmdmeta.SetDomain(dom, "event")
+	dom.AddCommand(&cobra.Command{Use: "consume", Run: func(*cobra.Command, []string) {}})
+	root.AddCommand(dom)
+	return dom
+}
+
+func TestPrepareDomainHelp_PreservesHandAuthoredLong(t *testing.T) {
+	const long = "Unified event consumption system. Use 'event consume <EventKey>'."
+	dom := domainCmd("Consume and manage real-time events", long)
+
+	if !PrepareDomainHelp(dom, nil) {
+		t.Fatal("PrepareDomainHelp returned false for a domain-tagged command")
+	}
+	if !strings.HasPrefix(dom.Long, long) {
+		t.Errorf("hand-authored Long must lead; got:\n%s", dom.Long)
+	}
+	if !strings.Contains(dom.Long, "Risk levels") {
+		t.Errorf("domain guidance should be appended; got:\n%s", dom.Long)
+	}
+
+	// Re-rendering must not append the guidance a second time.
+	PrepareDomainHelp(dom, nil)
+	if n := strings.Count(dom.Long, "Risk levels"); n != 1 {
+		t.Errorf("guidance appended %d times across re-renders, want 1:\n%s", n, dom.Long)
+	}
+}
+
+// A service domain carries only a Short at help time; it seeds the base.
+func TestPrepareDomainHelp_FallsBackToShort(t *testing.T) {
+	dom := domainCmd("Message and group chat management", "")
+	if !PrepareDomainHelp(dom, nil) {
+		t.Fatal("PrepareDomainHelp returned false for a domain-tagged command")
+	}
+	if !strings.HasPrefix(dom.Long, "Message and group chat management") {
+		t.Errorf("Short should seed Long when no hand-authored Long exists; got:\n%s", dom.Long)
+	}
+}

cmd/service/flaggroups.go

@@ -0,0 +1,211 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// Flag annotations the grouped service-method help renderer reads.
+const (
+	flagGroupAnnotation = "lark_flag_group" // display group key
+	flagSubAnnotation   = "lark_flag_sub"   // "required" | "optional" within API Parameters
+	flagNoteAnnotation  = "lark_flag_note"  // extra lines shown indented under a flag
+
+	groupParams    = "params"    // typed path/query flags
+	groupBody      = "body"      // --data, --file
+	groupRaw       = "raw"       // --params
+	groupExecution = "execution" // --as/--dry-run/--page-*/--yes
+	groupOutput    = "output"    // --output/--format/--jq
+
+	subRequired = "required"
+	subOptional = "optional"
+)
+
+// serviceFlagGroupOrder is the display order + titles of the flag groups. API
+// Parameters carries only typed path/query flags; raw --params, request body and
+// execution/output controls each get their own group so an agent can tell the
+// distinct input kinds apart.
+var serviceFlagGroupOrder = []struct{ key, title string }{
+	{groupParams, "API Parameters"},
+	{groupBody, "Request Body"},
+	{groupRaw, "Raw Parameter Input"},
+	{groupExecution, "Execution"},
+	{groupOutput, "Output"},
+}
+
+// applyGroupedUsage installs the grouped usage renderer on a service method
+// cmd: local flags via the grouped renderer instead of cobra's flat Flags:
+// list; global (inherited) flags and the Risk/Tips sections appended by the
+// root help func are unaffected. Rendered by hand rather than via
+// cmd.SetUsageTemplate: cobra lazy-links text/template on the first
+// SetUsageTemplate call, whose executor reaches reflect.Value.MethodByName —
+// that disables the linker's method-level dead-code elimination and costs
+// ~19 MB of binary size.
+func applyGroupedUsage(cmd *cobra.Command) {
+	cmd.SetUsageFunc(func(c *cobra.Command) error {
+		w := c.OutOrStderr()
+		fmt.Fprintf(w, "Usage:\n  %s\n", c.UseLine())
+		if c.HasAvailableLocalFlags() {
+			fmt.Fprintf(w, "\n%s\n", renderServiceFlagGroups(c))
+		}
+		if c.HasAvailableInheritedFlags() {
+			fmt.Fprintf(w, "\nGlobal Flags:\n%s\n", strings.TrimRight(c.InheritedFlags().FlagUsages(), " \t\n"))
+		}
+		return nil
+	})
+}
+
+func annotate(f *pflag.Flag, key string, vals []string) {
+	if f.Annotations == nil {
+		f.Annotations = map[string][]string{}
+	}
+	f.Annotations[key] = vals
+}
+
+// tagFlagGroup records a flag's display group (no-op if the flag is absent).
+func tagFlagGroup(fs *pflag.FlagSet, name, group string) {
+	if f := fs.Lookup(name); f != nil {
+		annotate(f, flagGroupAnnotation, []string{group})
+	}
+}
+
+func annotationOf(f *pflag.Flag, key string) []string {
+	if f.Annotations != nil {
+		return f.Annotations[key]
+	}
+	return nil
+}
+
+func flagGroupOf(f *pflag.Flag) string {
+	if v := annotationOf(f, flagGroupAnnotation); len(v) > 0 {
+		return v[0]
+	}
+	return ""
+}
+
+func flagSubOf(f *pflag.Flag) string {
+	if v := annotationOf(f, flagSubAnnotation); len(v) > 0 {
+		return v[0]
+	}
+	return ""
+}
+
+// renderServiceFlagGroups renders the command's local flags into ordered,
+// titled groups; the API Parameters group is further split into Required /
+// Optional. It is the body of the usage func applyGroupedUsage installs.
+func renderServiceFlagGroups(cmd *cobra.Command) string {
+	var b strings.Builder
+	seen := map[*pflag.Flag]bool{}
+	for _, g := range serviceFlagGroupOrder {
+		flags := groupFlags(cmd, g.key, seen)
+		if len(flags) == 0 {
+			continue
+		}
+		fmt.Fprintf(&b, "%s:\n", g.title)
+		if g.key == groupParams {
+			writeSection(&b, "  Required:", subFlags(flags, subRequired))
+			writeSection(&b, "  Optional:", subFlags(flags, subOptional))
+		} else {
+			writeSection(&b, "", flags)
+		}
+		fmt.Fprintln(&b)
+	}
+	// Anything untagged (e.g. -h/--help) goes last under "Other".
+	var other []*pflag.Flag
+	cmd.LocalFlags().VisitAll(func(f *pflag.Flag) {
+		if f.Hidden || seen[f] {
+			return
+		}
+		other = append(other, f)
+	})
+	if len(other) > 0 {
+		fmt.Fprintln(&b, "Other:")
+		writeSection(&b, "", other)
+	}
+	return strings.TrimRight(b.String(), "\n")
+}
+
+// groupFlags returns the visible local flags tagged with group key, marking them
+// seen so the trailing "Other" bucket only catches genuinely untagged flags.
+func groupFlags(cmd *cobra.Command, key string, seen map[*pflag.Flag]bool) []*pflag.Flag {
+	var flags []*pflag.Flag
+	cmd.LocalFlags().VisitAll(func(f *pflag.Flag) {
+		if f.Hidden || flagGroupOf(f) != key {
+			return
+		}
+		flags = append(flags, f)
+		seen[f] = true
+	})
+	return flags
+}
+
+func subFlags(flags []*pflag.Flag, sub string) []*pflag.Flag {
+	var out []*pflag.Flag
+	for _, f := range flags {
+		s := flagSubOf(f)
+		// Untagged subgroup defaults to Optional so nothing is dropped.
+		if s == sub || (s == "" && sub == subOptional) {
+			out = append(out, f)
+		}
+	}
+	return out
+}
+
+// writeSection prints an optional (sub)header and the flags, aligned in a
+// column, each flag row followed by its note lines indented under the usage.
+func writeSection(b *strings.Builder, header string, flags []*pflag.Flag) {
+	if len(flags) == 0 {
+		return
+	}
+	if header != "" {
+		fmt.Fprintf(b, "%s\n", header)
+	}
+	specs := make([]string, len(flags))
+	maxSpec := 0
+	for i, f := range flags {
+		specs[i] = flagSpec(f)
+		if len(specs[i]) > maxSpec {
+			maxSpec = len(specs[i])
+		}
+	}
+	for i, f := range flags {
+		_, usage := pflag.UnquoteUsage(f)
+		if showsDefault(f) {
+			usage += fmt.Sprintf(" (default %s)", f.DefValue)
+		}
+		fmt.Fprintf(b, "%-*s   %s\n", maxSpec, specs[i], strings.TrimSpace(usage))
+		for _, note := range annotationOf(f, flagNoteAnnotation) {
+			fmt.Fprintf(b, "%*s%s\n", maxSpec+3+4, "", note)
+		}
+	}
+}
+
+// flagSpec is pflag's "      --name type" / "  -x, --name type" left column.
+func flagSpec(f *pflag.Flag) string {
+	typeName, _ := pflag.UnquoteUsage(f)
+	spec := "      --" + f.Name
+	if f.Shorthand != "" && f.ShorthandDeprecated == "" {
+		spec = "  -" + f.Shorthand + ", --" + f.Name
+	}
+	if typeName != "" {
+		spec += " " + typeName
+	}
+	return spec
+}
+
+// showsDefault mirrors pflag's "non-zero default" rule for the flag types these
+// commands use, so the grouped rendering shows the same "(default x)" hints as
+// cobra's flat list.
+func showsDefault(f *pflag.Flag) bool {
+	switch f.DefValue {
+	case "", "0", "false", "[]":
+		return false
+	}
+	return true
+}

cmd/service/flaggroups_test.go

@@ -0,0 +1,118 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/meta"
+)
+
+func TestServiceFlagGroups_AgentContract(t *testing.T) {
+	method := map[string]interface{}{
+		"path":       "chats/:chat_id/members",
+		"httpMethod": "POST",
+		"parameters": map[string]interface{}{
+			"chat_id": map[string]interface{}{"type": "string", "location": "path", "required": true},
+			"member_id_type": map[string]interface{}{
+				"type": "string", "location": "query",
+				"options": []interface{}{
+					map[string]interface{}{"value": "open_id", "description": "以 open_id 标识用户"},
+					map[string]interface{}{"value": "user_id", "description": "以 user_id 标识用户"},
+				},
+			},
+		},
+		// Documented body field -> --data belongs under Request Body.
+		"requestBody": map[string]interface{}{
+			"id_list": map[string]interface{}{"type": "list", "required": true},
+		},
+	}
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(method), "create", "chat.members", nil)
+	out := renderServiceFlagGroups(cmd)
+
+	idx := func(s string) int { return strings.Index(out, s) }
+
+	// Section order: API Parameters → Request Body → Raw Parameter Input → Execution → Output.
+	iParams, iBody, iRaw, iExec, iOut := idx("API Parameters:"), idx("Request Body:"), idx("Raw Parameter Input:"), idx("Execution:"), idx("Output:")
+	for name, i := range map[string]int{"API Parameters": iParams, "Request Body": iBody, "Raw Parameter Input": iRaw, "Execution": iExec, "Output": iOut} {
+		if i < 0 {
+			t.Fatalf("missing section %q in:\n%s", name, out)
+		}
+	}
+	if !(iParams < iBody && iBody < iRaw && iRaw < iExec && iExec < iOut) {
+		t.Errorf("section order wrong:\n%s", out)
+	}
+
+	// Required/Optional subsections under API Parameters.
+	if i := idx("  Required:"); i < iParams || i > iBody {
+		t.Errorf("Required subsection misplaced:\n%s", out)
+	}
+	if i := idx("  Optional:"); i < iParams || i > iBody {
+		t.Errorf("Optional subsection misplaced:\n%s", out)
+	}
+
+	// Typed flags are API Parameters; required path flag under Required, enum
+	// flag under Optional with an inline "enum: ..." (not multi-line meanings).
+	if i := idx("--chat-id"); i < iParams || i > iBody {
+		t.Errorf("--chat-id not under API Parameters:\n%s", out)
+	}
+	// The redundant "<name>, required|optional." prefix is gone: required-ness is
+	// carried by the Required:/Optional: subheadings, and the snake-case --params
+	// key by the schema envelope — so it isn't echoed on every flag line.
+	if strings.Contains(out, "chat_id, required") || strings.Contains(out, "member_id_type, optional") {
+		t.Errorf("redundant <name>, required/optional prefix should not appear:\n%s", out)
+	}
+	if !strings.Contains(out, "enum: open_id=以 open_id 标识用户|user_id=以 user_id 标识用户") {
+		t.Errorf("expected compact enum value=meaning inline:\n%s", out)
+	}
+
+	// --data is Request Body; --params is Raw Parameter Input (NOT API Parameters)
+	// and carries the precedence rule.
+	if i := idx("--data"); i < iBody || i > iRaw {
+		t.Errorf("--data not under Request Body:\n%s", out)
+	}
+	if i := idx("--params"); i < iRaw || i > iExec {
+		t.Errorf("--params not under Raw Parameter Input:\n%s", out)
+	}
+	if !strings.Contains(out, "typed flags override matching keys in --params") {
+		t.Errorf("missing --params precedence rule:\n%s", out)
+	}
+
+	// Control flags land in Execution/Output.
+	if i := idx("--dry-run"); i < iExec || i > iOut {
+		t.Errorf("--dry-run not under Execution:\n%s", out)
+	}
+	if idx("--format") < iOut {
+		t.Errorf("--format not under Output:\n%s", out)
+	}
+
+	// The usage template is wired to the grouped renderer (no flat Flags: list).
+	if u := cmd.UsageString(); !strings.Contains(u, "API Parameters:") || strings.Contains(u, "\nFlags:\n") {
+		t.Errorf("usage template not grouped:\n%s", u)
+	}
+}
+
+// TestServiceFlagGroups_UndocumentedBodyIsRaw: a POST with no documented body
+// fields still offers --data (escape hatch) but must NOT imply a declared body —
+// it goes under Raw Parameter Input, not "Request Body".
+func TestServiceFlagGroups_UndocumentedBodyIsRaw(t *testing.T) {
+	method := map[string]interface{}{"path": "things/do", "httpMethod": "POST"} // POST, no requestBody, no params
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(method), "do", "things", nil)
+	out := renderServiceFlagGroups(cmd)
+
+	if strings.Contains(out, "Request Body:") {
+		t.Errorf("undocumented body must not render a Request Body section:\n%s", out)
+	}
+	iRaw, iData := strings.Index(out, "Raw Parameter Input:"), strings.Index(out, "--data")
+	if iRaw < 0 || iData < iRaw {
+		t.Errorf("--data not under Raw Parameter Input:\n%s", out)
+	}
+	if !strings.Contains(out, "no documented fields") {
+		t.Errorf("--data should be labeled a raw escape hatch:\n%s", out)
+	}
+}

cmd/service/paramflags.go

@@ -0,0 +1,166 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/meta"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+type boundParamFlag struct {
+	field meta.Field
+	read  func() interface{}
+}
+
+// paramsOnlyField is a path/query parameter that got no typed flag because its
+// kebab name is already taken by another flag (a standard flag like --format, or
+// a root persistent flag). It stays reachable via --params; the binder keeps it,
+// with the flag that claimed the name, so --help can show the exact --params form
+// and steer the reader off the wrong flag.
+type paramsOnlyField struct {
+	field   meta.Field
+	claimed *pflag.Flag
+}
+
+// paramFlagBinder owns one service method's generated typed param flags: it
+// registers them (kind, help, enum completion, reserved-name skip) and applies
+// the --params overlay, where a changed typed flag overrides its key in the
+// --params JSON. Holding the field<->flag binding here keeps the request builder
+// from re-deriving which flags map to which param keys.
+type paramFlagBinder struct {
+	bound      []boundParamFlag
+	paramsOnly []paramsOnlyField
+}
+
+// newParamFlagBinder registers one typed kebab flag per path/query parameter on
+// cmd and returns a binder for the --params overlay. A name already taken by
+// another flag is skipped — pflag panics on a local duplicate and a generated
+// flag would silently shadow a persistent one — and recorded as paramsOnly so
+// the parameter stays reachable (and discoverable) via --params. The taken set
+// is derived, not hand-listed: local flags (the standard set, registered before
+// this runs) via cmd, the lazily-added --help materialized here, and the root's
+// persistent flags via reserved (nil for direct callers that have no root).
+func newParamFlagBinder(cmd *cobra.Command, params []meta.Field, reserved *pflag.FlagSet) *paramFlagBinder {
+	cmd.InitDefaultHelpFlag() // materialize --help/-h so the local guard below sees it
+	b := &paramFlagBinder{}
+	for _, f := range params {
+		name := f.FlagName()
+		if claimed := flagClaiming(cmd, reserved, name); claimed != nil {
+			b.paramsOnly = append(b.paramsOnly, paramsOnlyField{field: f, claimed: claimed})
+			continue
+		}
+		read := registerTypedFlag(cmd.Flags(), name, f.CanonicalType(), paramFlagUsage(f))
+		if values := enumStrings(f.EnumValues()); len(values) > 0 {
+			cmdutil.RegisterFlagCompletion(cmd, name, func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+				return values, cobra.ShellCompDirectiveNoFileComp
+			})
+		}
+		// Group as an API parameter and mark required/optional for the
+		// Required/Optional subsections of the grouped --help renderer.
+		if fl := cmd.Flags().Lookup(name); fl != nil {
+			annotate(fl, flagGroupAnnotation, []string{groupParams})
+			sub := subOptional
+			if f.Required {
+				sub = subRequired
+			}
+			annotate(fl, flagSubAnnotation, []string{sub})
+		}
+		b.bound = append(b.bound, boundParamFlag{field: f, read: read})
+	}
+	return b
+}
+
+// flagClaiming returns the flag already occupying name (so a typed param flag
+// would collide), or nil when the name is free. It checks the command's own
+// flags (the standard set + the materialized --help) and the root's persistent
+// flags — so the reserved set is whatever is actually registered, never a
+// hand-kept list that drifts when a global flag is added.
+func flagClaiming(cmd *cobra.Command, reserved *pflag.FlagSet, name string) *pflag.Flag {
+	if fl := cmd.Flags().Lookup(name); fl != nil {
+		return fl
+	}
+	if reserved != nil {
+		return reserved.Lookup(name)
+	}
+	return nil
+}
+
+// paramsOnlyHelp renders the --help addendum for parameters that have no typed
+// flag, or "" when there are none. Per field: a copy-pasteable --params form,
+// the same fieldFacts a typed flag would show on its usage line, and what the
+// colliding flag actually does — so neither a human nor an agent sets the
+// wrong one (e.g. --format, which is the output format, not the API parameter).
+func (b *paramFlagBinder) paramsOnlyHelp() string {
+	if len(b.paramsOnly) == 0 {
+		return ""
+	}
+	var sb strings.Builder
+	sb.WriteString("\nParameters set via --params (no typed flag; the name is taken by another flag):\n")
+	for _, p := range b.paramsOnly {
+		name := p.field.Name
+		fmt.Fprintf(&sb, "  %s: --params '{%q: %s}'\n", name, name, paramExample(p.field))
+		for _, fact := range fieldFacts(p.field) {
+			fmt.Fprintf(&sb, "      %s\n", fact)
+		}
+		if p.claimed != nil {
+			fmt.Fprintf(&sb, "      do not use --%s (%s)\n", p.claimed.Name, p.claimed.Usage)
+		}
+	}
+	return sb.String()
+}
+
+// hasTypedFlag reports whether the binder registered a typed flag for the
+// param named name. False for params-only fields — a flag with the same kebab
+// name may exist (that's the collision), but it is not this param's input.
+// Nil-safe for direct buildServiceRequest callers that have no binder.
+func (b *paramFlagBinder) hasTypedFlag(name string) bool {
+	if b == nil {
+		return false
+	}
+	for _, pf := range b.bound {
+		if pf.field.Name == name {
+			return true
+		}
+	}
+	return false
+}
+
+// overlay lets an explicit typed flag override the same key in --params
+// (--params is the base). Only changed flags apply, so the --params-only path is
+// unchanged. A nil binder or cmd is a no-op.
+func (b *paramFlagBinder) overlay(cmd *cobra.Command, params map[string]interface{}) {
+	if b == nil || cmd == nil {
+		return
+	}
+	for _, pf := range b.bound {
+		if cmd.Flags().Changed(pf.field.FlagName()) {
+			params[pf.field.Name] = pf.read()
+		}
+	}
+}
+
+// registerTypedFlag registers one flag of the given canonical JSON-Schema kind
+// and returns a reader for its parsed value; the kind→pflag-type switch lives
+// only here.
+func registerTypedFlag(fs *pflag.FlagSet, name, kind, usage string) func() interface{} {
+	switch kind {
+	case "integer":
+		return flagReader(fs.Int(name, 0, usage))
+	case "boolean":
+		return flagReader(fs.Bool(name, false, usage))
+	case "array":
+		return flagReader(fs.StringArray(name, nil, usage))
+	default:
+		return flagReader(fs.String(name, "", usage))
+	}
+}
+
+func flagReader[T any](p *T) func() interface{} {
+	return func() interface{} { return *p }
+}

cmd/service/paramflags_test.go

@@ -0,0 +1,626 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/meta"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// imChatMembersCreate: POST chats/{chat_id}/members with one path param and one
+// optional enum query param — the canonical case from the screenshot feedback.
+func imChatMembersCreate() meta.Method {
+	return meta.FromMap(map[string]interface{}{
+		"path":       "chats/{chat_id}/members",
+		"httpMethod": "POST",
+		"parameters": map[string]interface{}{
+			"chat_id": map[string]interface{}{
+				"type": "string", "location": "path", "required": true,
+			},
+			"member_id_type": map[string]interface{}{
+				"type": "string", "location": "query", "required": false,
+				"options": []interface{}{
+					map[string]interface{}{"value": "open_id"},
+					map[string]interface{}{"value": "user_id"},
+				},
+			},
+		},
+	})
+}
+
+func TestServiceMethod_TypedFlagRegistered(t *testing.T) {
+	f := &cmdutil.Factory{}
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+
+	if cmd.Flags().Lookup("chat-id") == nil {
+		t.Error("expected generated --chat-id flag for path param chat_id")
+	}
+	if cmd.Flags().Lookup("member-id-type") == nil {
+		t.Error("expected generated --member-id-type flag for query param member_id_type")
+	}
+}
+
+// A query param literally named "format" kebab-collides with the global
+// --format flag. Generation must skip it (never re-register, never panic) and
+// leave the standard --format flag intact.
+func TestServiceMethod_TypedFlagReservedCollisionSkipped(t *testing.T) {
+	method := map[string]interface{}{
+		"path":       "messages",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"format": map[string]interface{}{"type": "string", "location": "query"},
+		},
+	}
+
+	var cmd *cobra.Command
+	func() {
+		defer func() {
+			if r := recover(); r != nil {
+				t.Fatalf("flag generation panicked on reserved-name collision: %v", r)
+			}
+		}()
+		cmd = NewCmdServiceMethod(&cmdutil.Factory{}, imSpec(), meta.FromMap(method), "list", "messages", nil)
+	}()
+
+	fl := cmd.Flags().Lookup("format")
+	if fl == nil || fl.DefValue != "json" {
+		t.Fatalf("standard --format flag must be preserved, got %+v", fl)
+	}
+}
+
+func TestServiceMethod_TypedFlag_DrivesPathParam(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--chat-id", "oc_abc123", "--data", `{"id_list":["ou_x"]}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "chats/oc_abc123/members") {
+		t.Errorf("expected URL with chat_id substituted from --chat-id, got:\n%s", stdout.String())
+	}
+}
+
+func TestServiceMethod_TypedFlag_DrivesQueryParam(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--chat-id", "oc_abc123", "--member-id-type", "open_id", "--data", `{}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "member_id_type") || !strings.Contains(out, "open_id") {
+		t.Errorf("expected query param member_id_type=open_id from flag, got:\n%s", out)
+	}
+}
+
+func TestServiceMethod_TypedFlag_AgreesWithParams(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--chat-id", "oc_abc123", "--params", `{"chat_id":"oc_abc123"}`, "--data", `{}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("same value via flag and --params should be accepted, got: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "chats/oc_abc123/members") {
+		t.Errorf("expected URL with chat_id, got:\n%s", stdout.String())
+	}
+}
+
+// --params is the base; an explicit typed flag overrides the same key.
+func TestServiceMethod_TypedFlag_OverridesParams(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--chat-id", "oc_flag", "--params", `{"chat_id":"oc_params"}`, "--data", `{}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "chats/oc_flag/members") {
+		t.Errorf("expected --chat-id to override --params chat_id, got:\n%s", out)
+	}
+	if strings.Contains(out, "oc_params") {
+		t.Errorf("--params value should have been overridden by the flag, got:\n%s", out)
+	}
+}
+
+// Override works for a non-string (integer) param too, exercising the int
+// register/read path end to end.
+func TestServiceMethod_TypedFlag_IntegerOverridesParams(t *testing.T) {
+	method := map[string]interface{}{
+		"path":       "messages",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"page_size": map[string]interface{}{"type": "integer", "location": "query"},
+		},
+	}
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(method), "list", "messages", nil)
+	cmd.SetArgs([]string{"--page-size", "100", "--params", `{"page_size":5}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "page_size") || !strings.Contains(out, "100") {
+		t.Errorf("expected --page-size 100 to override --params page_size=5, got:\n%s", out)
+	}
+}
+
+// Regression: with no typed flags passed, behavior is byte-identical to today.
+func TestServiceMethod_TypedFlag_OnlyParamsStillWorks(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--params", `{"chat_id":"oc_abc123"}`, "--data", `{}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "chats/oc_abc123/members") {
+		t.Errorf("expected URL with chat_id from --params, got:\n%s", stdout.String())
+	}
+}
+
+// Regression: --params null is valid JSON that unmarshals to a nil map. A typed
+// flag overlaying onto it must not panic (assignment to a nil map) — null is
+// treated as "no base params", with the flag value applied on top.
+func TestServiceMethod_TypedFlag_OverridesNullParams(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--chat-id", "oc_abc123", "--params", "null", "--data", `{}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("--params null with a typed flag should not error, got: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "chats/oc_abc123/members") {
+		t.Errorf("expected chat_id from --chat-id over null --params, got:\n%s", stdout.String())
+	}
+}
+
+// Startup smoke test: registering every embedded method must not panic on a
+// generated-flag name collision (pflag panics on duplicate registration, which
+// would crash the whole CLI at startup), and a known path param must surface as
+// a typed flag end to end.
+func TestRegisterServiceCommands_GeneratesFlagsNoPanic(t *testing.T) {
+	root := &cobra.Command{Use: "lark-cli"}
+	f := &cmdutil.Factory{}
+
+	defer func() {
+		if r := recover(); r != nil {
+			t.Fatalf("registering all service commands panicked: %v", r)
+		}
+	}()
+	RegisterServiceCommands(root, f)
+
+	create, _, err := root.Find([]string{"im", "chat.members", "create"})
+	if err != nil {
+		t.Fatalf("im chat.members create not registered: %v", err)
+	}
+	if create.Flags().Lookup("chat-id") == nil {
+		t.Error("expected generated --chat-id flag on im chat.members create")
+	}
+}
+
+// Locks the boolean and array branches of bindParamFlag end to end (string and
+// integer are covered above): a bool flag yields true and a repeatable array
+// flag yields all its elements in the request.
+func TestServiceMethod_TypedFlag_BoolAndArrayKinds(t *testing.T) {
+	method := map[string]interface{}{
+		"path":       "items",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"with_deleted": map[string]interface{}{"type": "boolean", "location": "query"},
+			"ids":          map[string]interface{}{"type": "list", "location": "query"},
+		},
+	}
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(method), "list", "items", nil)
+	cmd.SetArgs([]string{"--with-deleted", "--ids", "a", "--ids", "b", "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{"with_deleted", "true", "ids", "\"a\"", "\"b\""} {
+		if !strings.Contains(out, want) {
+			t.Errorf("expected dry-run output to contain %q, got:\n%s", want, out)
+		}
+	}
+}
+
+// Override (--params base, typed flag wins) is covered for string and integer
+// above; this locks the same semantics for the boolean and array kinds.
+func TestServiceMethod_TypedFlag_BoolAndArrayOverrideParams(t *testing.T) {
+	method := map[string]interface{}{
+		"path":       "items",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"with_deleted": map[string]interface{}{"type": "boolean", "location": "query"},
+			"ids":          map[string]interface{}{"type": "list", "location": "query"},
+		},
+	}
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), meta.FromMap(method), "list", "items", nil)
+	cmd.SetArgs([]string{
+		"--params", `{"with_deleted":false,"ids":["from_params"]}`,
+		"--with-deleted", "--ids", "a", "--ids", "b",
+		"--dry-run",
+	})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{"with_deleted", "true", "\"a\"", "\"b\""} {
+		if !strings.Contains(out, want) {
+			t.Errorf("expected flag to override --params (want %q), got:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, "from_params") {
+		t.Errorf("--params array value should have been overridden by --ids, got:\n%s", out)
+	}
+}
+
+// A param whose kebab name collides with a global flag (here "format" vs the
+// global --format) gets no typed flag, but the collision is no longer silent:
+// non-colliding params still get flags, the global --format is untouched, and
+// --help shows the exact --params form and steers the reader off --format.
+func TestServiceMethod_ParamsOnly_HelpSteersToParams(t *testing.T) {
+	method := map[string]interface{}{
+		"path":       "things/{thing_id}",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"thing_id": map[string]interface{}{"type": "string", "location": "path", "required": true},
+			"format": map[string]interface{}{"type": "string", "location": "query", "min": "1", "max": "64", "description": "返回的消息体格式。", "options": []interface{}{
+				map[string]interface{}{"value": "full"},
+				map[string]interface{}{"value": "metadata"},
+			}},
+		},
+	}
+	cmd := NewCmdServiceMethod(&cmdutil.Factory{}, imSpec(), meta.FromMap(method), "get", "things", nil)
+
+	if cmd.Flags().Lookup("thing-id") == nil {
+		t.Error("non-colliding param should still get a typed --thing-id flag")
+	}
+	if fl := cmd.Flags().Lookup("format"); fl == nil || fl.DefValue != "json" {
+		t.Fatalf("global --format must be preserved (not shadowed), got %+v", fl)
+	}
+	for _, want := range []string{`--params '{"format"`, "返回的消息体格式", "full", "metadata", "min: 1, max: 64", "do not use --format"} {
+		if !strings.Contains(cmd.Long, want) {
+			t.Errorf("help should contain %q so the reader uses --params, not --format; got:\n%s", want, cmd.Long)
+		}
+	}
+}
+
+// The collision guard derives reserved names from the actual flag sets — local
+// flags plus the root's persistent flags passed in — so a future persistent
+// flag is covered with no hand-maintained list. Here a param named "profile"
+// (a root persistent flag) is skipped while a normal param is bound.
+func TestParamFlagBinder_PersistentFlagReserved(t *testing.T) {
+	cmd := &cobra.Command{Use: "x"}
+	reserved := pflag.NewFlagSet("root", pflag.ContinueOnError)
+	reserved.String("profile", "", "use a specific profile")
+
+	m := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+		"profile": map[string]interface{}{"type": "string", "location": "query"},
+		"id":      map[string]interface{}{"type": "string", "location": "path"},
+	}})
+	b := newParamFlagBinder(cmd, m.Params(), reserved)
+
+	if cmd.Flags().Lookup("id") == nil {
+		t.Error("non-colliding param should get a typed flag")
+	}
+	if cmd.Flags().Lookup("profile") != nil {
+		t.Error("param colliding with a reserved persistent flag must not be registered")
+	}
+	found := false
+	for _, p := range b.paramsOnly {
+		if p.field.Name == "profile" {
+			found = true
+		}
+	}
+	if !found {
+		t.Error("colliding param should be recorded for the --params help note")
+	}
+}
+
+// boolIntQueryMethod is the fixture for the zero-value semantics tests: one
+// boolean and one integer query param, where false and 0 are meaningful values.
+func boolIntQueryMethod(required bool) meta.Method {
+	return meta.FromMap(map[string]interface{}{
+		"path":       "items",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"with_deleted": map[string]interface{}{"type": "boolean", "location": "query", "required": required},
+			"page_size":    map[string]interface{}{"type": "integer", "location": "query"},
+		},
+	})
+}
+
+// Presence is intent: a typed flag is only overlaid when explicitly Changed,
+// so --flag=false / --flag 0 are real values and must be sent — not silently
+// dropped as "empty", which would let the API default win over an explicit
+// user choice.
+func TestServiceMethod_TypedFlag_ExplicitFalseAndZeroAreSent(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), boolIntQueryMethod(false), "list", "items", nil)
+	cmd.SetArgs([]string{"--with-deleted=false", "--page-size", "0", "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{`"with_deleted": false`, `"page_size": 0`} {
+		if !strings.Contains(out, want) {
+			t.Errorf("explicit zero value must be sent (want %s), got:\n%s", want, out)
+		}
+	}
+}
+
+// An explicitly provided false satisfies a required query parameter — the
+// pre-flight must not report "missing" for a value the user just set.
+func TestServiceMethod_TypedFlag_ExplicitFalseSatisfiesRequired(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), boolIntQueryMethod(true), "list", "items", nil)
+	cmd.SetArgs([]string{"--with-deleted=false", "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("required param explicitly set to false must pass pre-flight, got: %v", err)
+	}
+	if !strings.Contains(stdout.String(), `"with_deleted": false`) {
+		t.Errorf("explicit false must be sent, got:\n%s", stdout.String())
+	}
+}
+
+// The same presence-is-intent rule applies to the --params JSON base: a key
+// deliberately written as false/0 is sent. (Zero values used to be silently
+// dropped; this locks the corrected semantics as the contract.)
+func TestServiceMethod_Params_JSONZeroValuesAreSent(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), boolIntQueryMethod(false), "list", "items", nil)
+	cmd.SetArgs([]string{"--params", `{"with_deleted":false,"page_size":0}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{`"with_deleted": false`, `"page_size": 0`} {
+		if !strings.Contains(out, want) {
+			t.Errorf("--params zero value must be sent (want %s), got:\n%s", want, out)
+		}
+	}
+}
+
+// "" stays unusable: a required parameter fed an empty-string placeholder is
+// still caught by the friendly pre-flight error, not sent as an empty value.
+func TestServiceMethod_Params_EmptyStringStillMissing(t *testing.T) {
+	method := meta.FromMap(map[string]interface{}{
+		"path":       "items",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"user_id_type": map[string]interface{}{"type": "string", "location": "query", "required": true},
+		},
+	})
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), method, "list", "items", nil)
+	cmd.SetArgs([]string{"--params", `{"user_id_type":""}`, "--dry-run"})
+
+	err := cmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "missing required query parameter") {
+		t.Fatalf("empty string for a required param should still pre-flight error, got: %v", err)
+	}
+}
+
+// A declared optional query param fed "" is dropped (unusable value), not sent
+// as an empty query value — the declared-param loop owns the decision and the
+// undeclared passthrough must not resurrect it. Undeclared keys stay the
+// verbatim raw escape hatch.
+func TestServiceMethod_Params_EmptyOptionalDroppedUndeclaredKept(t *testing.T) {
+	method := meta.FromMap(map[string]interface{}{
+		"path":       "items",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"user_id_type": map[string]interface{}{"type": "string", "location": "query"},
+		},
+	})
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), method, "list", "items", nil)
+	cmd.SetArgs([]string{"--params", `{"user_id_type":"","custom_key":"v1"}`, "--dry-run"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if strings.Contains(out, "user_id_type") {
+		t.Errorf("declared optional param with empty value must be dropped, got:\n%s", out)
+	}
+	if !strings.Contains(out, `"custom_key": "v1"`) {
+		t.Errorf("undeclared key must pass through verbatim, got:\n%s", out)
+	}
+}
+
+// min/max from the metadata surface on the typed flag's help line, in the same
+// vocabulary as the envelope's minimum/maximum.
+func TestParamFlagUsage_Bounds(t *testing.T) {
+	cases := []struct{ name, min, max, want string }{
+		{"both", "1", "100", "min: 1, max: 100"},
+		{"min only", "1", "", "min: 1"},
+		{"max only", "", "64", "max: 64"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			fields := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+				"page_size": map[string]interface{}{"type": "integer", "location": "query", "min": tc.min, "max": tc.max},
+			}}).Params()
+			if usage := paramFlagUsage(fields[0]); !strings.Contains(usage, tc.want) {
+				t.Errorf("usage = %q, want contains %q", usage, tc.want)
+			}
+		})
+	}
+	t.Run("no bounds, no clause", func(t *testing.T) {
+		fields := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+			"page_token": map[string]interface{}{"type": "string", "location": "query"},
+		}}).Params()
+		if usage := paramFlagUsage(fields[0]); strings.Contains(usage, "min:") || strings.Contains(usage, "max:") {
+			t.Errorf("usage without bounds should not mention min/max, got %q", usage)
+		}
+	})
+}
+
+// The sanitized field description rides the help line — a bare name like
+// user_mailbox_id carries no meaning. The cut is at note separators (;), NOT
+// at sentence ends (。): the later sentence often holds the key affordance.
+func TestParamFlagUsage_Description(t *testing.T) {
+	fields := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+		"user_mailbox_id": map[string]interface{}{
+			"type": "string", "location": "path", "required": true,
+			"description": `用户邮箱地址。当使用用户身份访问时，可以输入"me"代表当前调用接口用户;后续补充说明不该出现`,
+		},
+	}}).Params()
+	usage := paramFlagUsage(fields[0])
+	if !strings.Contains(usage, `可以输入"me"代表当前调用接口用户`) {
+		t.Errorf("description must keep full sentences up to the note separator, got %q", usage)
+	}
+	if strings.Contains(usage, "补充说明") {
+		t.Errorf("text after the note separator must be cut, got %q", usage)
+	}
+
+	t.Run("long description truncated", func(t *testing.T) {
+		fields := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+			"x": map[string]interface{}{
+				"type": "string", "location": "query",
+				"description": strings.Repeat("长", 80),
+			},
+		}}).Params()
+		usage := paramFlagUsage(fields[0])
+		if !strings.Contains(usage, "...") {
+			t.Errorf("long description should be truncated with ellipsis, got %q", usage)
+		}
+		if strings.Contains(usage, strings.Repeat("长", 61)) {
+			t.Errorf("description should not exceed the cap, got %q", usage)
+		}
+	})
+
+	t.Run("trailing sentence punctuation trimmed", func(t *testing.T) {
+		fields := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+			"x": map[string]interface{}{
+				"type": "string", "location": "query", "description": "返回格式。",
+			},
+		}}).Params()
+		if usage := paramFlagUsage(fields[0]); strings.Contains(usage, "。.") {
+			t.Errorf("clause join must not double the punctuation, got %q", usage)
+		}
+	})
+}
+
+// Pins the convergence contract: the params-only addendum renders the SAME
+// fieldFacts list the typed flag's usage line joins inline — a fact added to
+// fieldFacts reaches both surfaces, and neither can drift over what a param's
+// help says (the addendum once rendered values-only enums and silently lacked
+// the API default).
+func TestParamHelp_BothSurfacesRenderFieldFacts(t *testing.T) {
+	f := meta.FromMap(map[string]interface{}{"parameters": map[string]interface{}{
+		"mode": map[string]interface{}{
+			"type": "string", "location": "query",
+			"description": "模式选择。",
+			"default":     "fast",
+			"min":         "1", "max": "8",
+			"options": []interface{}{
+				map[string]interface{}{"value": "fast", "description": "快速"},
+				map[string]interface{}{"value": "full"},
+			},
+		},
+	}}).Params()[0]
+
+	facts := fieldFacts(f)
+	if len(facts) != 4 { // description, enum, bounds, API default
+		t.Fatalf("fieldFacts = %v, want 4 facts", facts)
+	}
+	usage := paramFlagUsage(f)
+	help := (&paramFlagBinder{paramsOnly: []paramsOnlyField{{field: f}}}).paramsOnlyHelp()
+	for _, fact := range facts {
+		if !strings.Contains(usage, fact) {
+			t.Errorf("usage line missing fact %q: %q", fact, usage)
+		}
+		if !strings.Contains(help, fact) {
+			t.Errorf("params-only addendum missing fact %q:\n%s", fact, help)
+		}
+	}
+}
+
+// Bounds reach the registered flag's help end to end.
+func TestServiceMethod_TypedFlag_HelpShowsBounds(t *testing.T) {
+	method := meta.FromMap(map[string]interface{}{
+		"path":       "items",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"page_size": map[string]interface{}{"type": "integer", "location": "query", "min": "1", "max": "100", "default": "20"},
+		},
+	})
+	cmd := NewCmdServiceMethod(&cmdutil.Factory{}, imSpec(), method, "list", "items", nil)
+	fl := cmd.Flags().Lookup("page-size")
+	if fl == nil {
+		t.Fatal("expected generated --page-size flag")
+	}
+	if !strings.Contains(fl.Usage, "min: 1, max: 100") {
+		t.Errorf("flag usage should carry bounds, got %q", fl.Usage)
+	}
+}
+
+// The missing-required hint must name both recovery paths — the typed flag and
+// the --params fallback — so a reader who only knows one input style can
+// proceed without a round-trip through schema.
+func TestServiceMethod_MissingRequired_HintNamesFlagAndParams(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), imChatMembersCreate(), "create", "chat.members", nil)
+	cmd.SetArgs([]string{"--data", `{"id_list":["ou_x"]}`, "--dry-run"})
+
+	err := cmd.Execute()
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	for _, want := range []string{"--chat-id", `--params '{"chat_id": "<value>"}'`, "lark-cli schema im.chat.members.create"} {
+		if !strings.Contains(ve.Hint, want) {
+			t.Errorf("hint %q should contain %q", ve.Hint, want)
+		}
+	}
+}
+
+// A params-only required field (kebab name claimed by the standard --format
+// flag) has no typed flag to offer: the hint must give only the --params form,
+// never steer the reader to the colliding flag.
+func TestServiceMethod_MissingRequired_ParamsOnlyHintSkipsFlag(t *testing.T) {
+	method := meta.FromMap(map[string]interface{}{
+		"path":       "messages",
+		"httpMethod": "GET",
+		"parameters": map[string]interface{}{
+			"format": map[string]interface{}{"type": "string", "location": "query", "required": true},
+		},
+	})
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, imSpec(), method, "list", "messages", nil)
+	cmd.SetArgs([]string{"--dry-run"})
+
+	err := cmd.Execute()
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if !strings.Contains(ve.Hint, `--params '{"format": "<value>"}'`) {
+		t.Errorf("hint %q should carry the --params form", ve.Hint)
+	}
+	if strings.Contains(ve.Hint, "set --format") {
+		t.Errorf("hint %q must not steer to the colliding --format flag", ve.Hint)
+	}
+}

cmd/service/paramhelp.go

@@ -0,0 +1,177 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Help rendering for generated param flags. fieldFacts is the single list of
+// agent-relevant facts a param exposes; every help surface (the typed flag's
+// usage line, the params-only --params addendum) renders that one list, so the
+// surfaces cannot drift over which facts exist. Values come from the
+// meta.Field accessors, so nothing here depends on internal/schema.
+
+package service
+
+import (
+	"fmt"
+	"regexp"
+	"strconv"
+	"strings"
+
+	"github.com/larksuite/cli/internal/meta"
+	"github.com/larksuite/cli/internal/util"
+)
+
+// fieldFacts returns a param field's facts in display order, each as a compact
+// one-line clause: the sanitized description, the allowed enum values (with
+// meanings), the min/max constraint, and the API default. This is the ONE
+// place that decides what a param's help says — add a fact here (e.g. a future
+// deprecation marker) and every surface shows it. Unabridged prose and
+// per-option detail stay in `lark-cli schema`.
+func fieldFacts(f meta.Field) []string {
+	var facts []string
+	if d := sanitizeFieldDesc(f.Description); d != "" {
+		facts = append(facts, d)
+	}
+	if f.CanonicalType() == "boolean" {
+		// cobra shows no type word for bools and swallows a separate value as a
+		// positional, so spell out the presence-only contract.
+		facts = append(facts, "bool flag (presence = true; omit for false; takes no value)")
+	}
+	if opts := f.EnumOptions(); len(opts) > 0 {
+		facts = append(facts, "enum: "+formatEnumInline(opts))
+	}
+	if b := formatBoundsInline(f); b != "" {
+		facts = append(facts, b)
+	}
+	if s := literalStr(f.CoercedDefault()); s != "" {
+		facts = append(facts, "API default: "+s)
+	}
+	return facts
+}
+
+// paramFlagUsage renders the typed param flag's help line: the field's facts
+// joined inline. Required/optional is not repeated here — the grouped help's
+// Required:/Optional: subheadings already partition the flags — and the
+// snake-case --params key is carried by the schema envelope (each param's
+// property + "flag") and the params-only addendum, so it isn't echoed on every
+// line either. Returns "" when the field has no facts (cobra then shows the bare
+// flag with its type).
+func paramFlagUsage(f meta.Field) string {
+	return strings.Join(fieldFacts(f), ". ")
+}
+
+// paramExample picks a concrete sample for a params-only field's --help snippet:
+// its first allowed enum value, else its example, else a placeholder.
+func paramExample(f meta.Field) string {
+	if vals := enumStrings(f.EnumValues()); len(vals) > 0 {
+		return fmt.Sprintf("%q", vals[0])
+	}
+	if s := literalStr(f.CoercedExample()); s != "" {
+		return fmt.Sprintf("%q", s)
+	}
+	return `"<value>"`
+}
+
+var markdownLinkRe = regexp.MustCompile(`\[([^\]]*)\]\([^)]*\)`)
+
+// inlineClause compresses metadata prose into one help clause: markdown links
+// keep their text, the clause cuts at the first rune in stops, whitespace
+// collapses, trailing punctuation goes — sentence enders (the clause join adds
+// its own) and connectors a cut can strand, like a colon introducing a list the
+// newline cut dropped — and the result caps at max runes. The two policies
+// below differ only in where they cut and how much they keep.
+func inlineClause(s, stops string, max int) string {
+	if s == "" {
+		return ""
+	}
+	s = markdownLinkRe.ReplaceAllString(s, "$1")
+	// Backquotes must go: pflag's UnquoteUsage treats a backquoted word in a
+	// flag's usage string as the flag's metavar, so a description like wiki
+	// space_id's "可替换为`my_library`" would render the flag as
+	// "--space-id my_library" instead of "--space-id string".
+	s = strings.ReplaceAll(s, "`", "")
+	if i := strings.IndexAny(s, stops); i >= 0 {
+		s = s[:i]
+	}
+	s = strings.Join(strings.Fields(s), " ")
+	s = strings.TrimRight(s, "。.：:，,、")
+	return util.TruncateStrWithEllipsis(s, max)
+}
+
+// sanitizeOptionDesc is the enum-option policy: many values share one line, so
+// keep only the first clause (cut at 。 too) and stay ultra-compact.
+func sanitizeOptionDesc(s string) string { return inlineClause(s, "。；;\n\r", 40) }
+
+// sanitizeFieldDesc is the field-description policy: one line per field, so
+// keep full sentences and cut only at note separators (meta_data appends
+// bullet notes after ;/；) — the later sentence often carries the key
+// affordance, e.g. user_mailbox_id's `可以输入"me"`. The trailing doc
+// cross-reference is dropped first (see cutDocRef).
+func sanitizeFieldDesc(s string) string { return inlineClause(cutDocRef(s), "；;\n\r", 60) }
+
+// docRefRe matches a "see the docs" breadcrumb (更多信息参见…/获取方式见…/详见…).
+// On the compact flag line the markdown link's URL is stripped, so the
+// breadcrumb is a dead pointer — drop it. Anchored on a leading clause separator
+// so a subject that runs straight into the phrase isn't orphaned.
+var docRefRe = regexp.MustCompile(`[。；;，,、]\s*(更多信息|获取方式|获取方法|详见|[请可]?参[见考阅])`)
+
+// cutDocRef truncates s at the first doc-reference breadcrumb.
+func cutDocRef(s string) string {
+	if loc := docRefRe.FindStringIndex(s); loc != nil {
+		return s[:loc[0]]
+	}
+	return s
+}
+
+// formatEnumInline renders allowed values for the help line: "v=meaning" when
+// the value carries a (sanitized, truncated) description — so opaque numeric
+// enums like succeed_type read as "0=…|1=…|2=…" — else just "v". Full meanings
+// live in the envelope's enumDescriptions / `lark-cli schema`.
+func formatEnumInline(opts []meta.EnumOption) string {
+	items := make([]string, len(opts))
+	for i, o := range opts {
+		if d := sanitizeOptionDesc(o.Description); d != "" {
+			items[i] = fmt.Sprintf("%v=%s", o.Value, d)
+		} else {
+			items[i] = fmt.Sprintf("%v", o.Value)
+		}
+	}
+	return strings.Join(items, "|")
+}
+
+// formatBoundsInline renders the field's min/max constraint ("min: 1, max:
+// 100", or the single declared side), or "" when the field declares neither.
+// The vocabulary matches the envelope's minimum/maximum, so help and `lark-cli
+// schema` state the same constraint.
+func formatBoundsInline(f meta.Field) string {
+	min, max := f.MinBound(), f.MaxBound()
+	switch {
+	case min != nil && max != nil:
+		return fmt.Sprintf("min: %s, max: %s", formatBound(*min), formatBound(*max))
+	case min != nil:
+		return "min: " + formatBound(*min)
+	case max != nil:
+		return "max: " + formatBound(*max)
+	}
+	return ""
+}
+
+// formatBound renders a bound without a float artifact (100 not 100.000000).
+func formatBound(v float64) string {
+	return strconv.FormatFloat(v, 'f', -1, 64)
+}
+
+// literalStr renders a coerced literal (default/example) for flag help,
+// returning "" for a nil or empty value so the caller can omit the clause.
+func literalStr(v interface{}) string {
+	if v == nil {
+		return ""
+	}
+	return fmt.Sprintf("%v", v)
+}
+
+func enumStrings(enum []interface{}) []string {
+	out := make([]string, 0, len(enum))
+	for _, e := range enum {
+		out = append(out, fmt.Sprintf("%v", e))
+	}
+	return out
+}

cmd/service/sanitize_test.go

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestSanitizeOptionDesc(t *testing.T) {
+	cases := map[string]string{
+		"":                         "",
+		"以 open_id 标识用户":           "以 open_id 标识用户",
+		"中文。English second clause": "中文",         // first clause only (。)
+		"head；tail":                "head",       // first clause (；)
+		"line one\nline two":       "line one",   // first clause (newline)
+		"  spaced   out  ":         "spaced out", // whitespace collapsed
+		"see [飞书后台](https://x/admin) 详情": "see 飞书后台 详情", // markdown link -> text, url dropped
+	}
+	for in, want := range cases {
+		if got := sanitizeOptionDesc(in); got != want {
+			t.Errorf("sanitizeOptionDesc(%q) = %q, want %q", in, got, want)
+		}
+	}
+
+	// Truncation: a long single clause is cut to 40 runes with an ellipsis,
+	// rune-safe (no split mid-character).
+	long := strings.Repeat("文", 60)
+	got := sanitizeOptionDesc(long)
+	if r := []rune(got); len(r) != 40 || !strings.HasSuffix(got, "...") {
+		t.Errorf("truncation = %q (%d runes), want 40 runes ending in ...", got, len(r))
+	}
+}
+
+func TestSanitizeFieldDesc_TrimsDanglingPunctuation(t *testing.T) {
+	// A clause cut can strand a connector (e.g. a colon introducing a list the
+	// newline cut drops, as in im.reactions.list's message_id); the help line
+	// joiner then renders "…获取方式：." — so dangling punctuation must go too.
+	cases := map[string]string{
+		"待查询的消息ID。ID 获取方式：\n- 调用接口获取": "待查询的消息ID。ID 获取方式",
+		"see the list below:\nitem":   "see the list below",
+		"逗号结尾，\n下一行":                  "逗号结尾",
+	}
+	for in, want := range cases {
+		if got := sanitizeFieldDesc(in); got != want {
+			t.Errorf("sanitizeFieldDesc(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestSanitizeFieldDesc_StripsBackquotes(t *testing.T) {
+	// pflag's UnquoteUsage takes a backquoted word in a flag's usage string as
+	// the flag's metavar: wiki space_id's description rendered the flag as
+	// "--space-id my_library" instead of "--space-id string".
+	in := "[知识空间id](https://x/wiki)，如果查询我的文档库可替换为`my_library`"
+	want := "知识空间id，如果查询我的文档库可替换为my_library"
+	if got := sanitizeFieldDesc(in); got != want {
+		t.Errorf("sanitizeFieldDesc(%q) = %q, want %q", in, got, want)
+	}
+}

cmd/service/service.go

@@ -0,0 +1,746 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"sort"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/apicatalog"
+	"github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/client"
+	"github.com/larksuite/cli/internal/cmdmeta"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/credential"
+	"github.com/larksuite/cli/internal/errclass"
+	"github.com/larksuite/cli/internal/meta"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/validate"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// RegisterServiceCommands registers all service commands from from_meta specs.
+func RegisterServiceCommands(parent *cobra.Command, f *cmdutil.Factory) {
+	RegisterServiceCommandsWithContext(context.Background(), parent, f)
+}
+
+func RegisterServiceCommandsWithContext(ctx context.Context, parent *cobra.Command, f *cmdutil.Factory) {
+	RegisterServiceCommandsFromCatalog(ctx, parent, f, registry.RuntimeCatalog())
+}
+
+func RegisterServiceCommandsFromCatalog(ctx context.Context, parent *cobra.Command, f *cmdutil.Factory, catalog apicatalog.Catalog) {
+	// Drive the service list from the same navigation catalog the method walk
+	// uses, so registration is catalog-sourced end to end. Kept as a per-service
+	// loop rather than a flat WalkMethods(nil) drive precisely so a service with
+	// no methods still gets its bare command (WalkMethods yields one ref per
+	// method, so empty services would vanish).
+	for _, svc := range catalog.Services() {
+		if svc.Name == "" || svc.ServicePath == "" {
+			continue
+		}
+		registerServiceWithContext(ctx, parent, svc, f)
+	}
+}
+
+func registerService(parent *cobra.Command, svc meta.Service, f *cmdutil.Factory) {
+	registerServiceWithContext(context.Background(), parent, svc, f)
+}
+
+func registerServiceWithContext(ctx context.Context, parent *cobra.Command, svc meta.Service, f *cmdutil.Factory) {
+	svcCmd := ensureChildCommand(parent, svc.Name, serviceShort(svc))
+
+	// Build the service's subtree from the catalog's method walk
+	// (apicatalog.ServiceMethods recurses nested resources), so the command tree
+	// is sourced from the same navigation Module as schema/scope rather than a
+	// hand-rolled resource/method walk. Each ref's ResourcePath becomes the
+	// resource-command chain — one level for a flat dotted resource like
+	// "chat.members", deeper for genuinely nested resources. A service with no
+	// methods keeps its bare command (svcCmd is created above regardless).
+	refs := apicatalog.ServiceMethods(svc, nil)
+
+	// Collect each resource's verbs up front so resourceShort can summarize a
+	// resource as its verb list from the first ensureChildCommand call.
+	verbs := map[string][]string{}
+	for _, ref := range refs {
+		key := strings.Join(ref.ResourcePath, ".")
+		verbs[key] = append(verbs[key], ref.Method.Name)
+	}
+
+	for _, ref := range refs {
+		resCmd := svcCmd
+		var path []string
+		for _, seg := range ref.ResourcePath {
+			path = append(path, seg)
+			resCmd = ensureChildCommand(resCmd, seg, resourceShort(seg, verbs[strings.Join(path, ".")]))
+		}
+		resCmd.AddCommand(buildMethodCommand(ctx, f, newMethodCommandSpec(ref), nil, parent.PersistentFlags()))
+	}
+}
+
+// resourceShort summarizes a resource as its sorted verb list, or the
+// "<name> operations" placeholder for an intermediate group with no methods.
+func resourceShort(seg string, verbs []string) string {
+	if len(verbs) == 0 {
+		return seg + " operations"
+	}
+	sorted := append([]string(nil), verbs...)
+	sort.Strings(sorted)
+	return strings.Join(sorted, ", ")
+}
+
+// serviceShort is the service command's help summary: the localized description
+// from the registry, falling back to the metadata's own description.
+func serviceShort(svc meta.Service) string {
+	if d := registry.GetServiceDescription(svc.Name, "en"); d != "" {
+		return d
+	}
+	return svc.Description
+}
+
+// ensureChildCommand returns the child of parent named name, creating it (with
+// short) when absent — so re-registration merges into an existing command tree
+// instead of duplicating a level.
+func ensureChildCommand(parent *cobra.Command, name, short string) *cobra.Command {
+	for _, c := range parent.Commands() {
+		if c.Name() == name {
+			cmdmeta.SetSource(c, cmdmeta.SourceService, true)
+			return c
+		}
+	}
+	cmd := &cobra.Command{Use: name, Short: short}
+	cmdmeta.SetSource(cmd, cmdmeta.SourceService, true)
+	parent.AddCommand(cmd)
+	return cmd
+}
+
+// ServiceMethodOptions holds all inputs for a dynamically registered service method command.
+type ServiceMethodOptions struct {
+	Factory     *cmdutil.Factory
+	Cmd         *cobra.Command
+	Ctx         context.Context
+	ServicePath string
+	Method      meta.Method
+	SchemaPath  string
+
+	// Flags
+	Params     string
+	Data       string
+	As         core.Identity
+	Output     string
+	PageAll    bool
+	PageLimit  int
+	PageDelay  int
+	Format     string
+	JqExpr     string
+	DryRun     bool
+	File       string   // --file flag value
+	FileFields []string // auto-detected file field names from metadata
+
+	// binder owns the generated typed param flags — registration and the
+	// --params overlay — replacing the raw paramFlags side-channel.
+	binder *paramFlagBinder
+}
+
+// detectFileFields returns the request-body file-upload field names.
+func detectFileFields(m meta.Method) []string {
+	files := m.Files()
+	if len(files) == 0 {
+		return nil
+	}
+	names := make([]string, len(files))
+	for i, f := range files {
+		names[i] = f.Name
+	}
+	return names
+}
+
+// NewCmdServiceMethod creates a command for a dynamically registered service method.
+func NewCmdServiceMethod(f *cmdutil.Factory, svc meta.Service, m meta.Method, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
+	return NewCmdServiceMethodWithContext(context.Background(), f, svc, m, name, resName, runF)
+}
+
+// NewCmdServiceMethodWithContext builds the command for one service method from
+// its (service, resource, method) coordinates, deriving the methodCommandSpec
+// via an apicatalog.MethodRef so direct callers and the catalog-driven
+// registration assemble the command identically.
+func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, svc meta.Service, m meta.Method, name, resName string, runF func(*ServiceMethodOptions) error) *cobra.Command {
+	m.Name = name
+	ref := apicatalog.MethodRef{Service: svc, ResourcePath: []string{resName}, Method: m}
+	// No root in scope here; persistent-flag collisions don't apply to a
+	// standalone command, and local/standard-flag collisions are still caught.
+	return buildMethodCommand(ctx, f, newMethodCommandSpec(ref), runF, nil)
+}
+
+// methodCommandSpec is the static description of one generated service method
+// command, read off an apicatalog.MethodRef — the single place command
+// construction gets the method's facts (schema path, HTTP base path, risk,
+// identities, params, file fields, request-body support), so the cobra command
+// is assembled from a typed spec rather than recomputing paths/flags inline.
+type methodCommandSpec struct {
+	method      meta.Method
+	schemaPath  string       // "service.resource.method", for the --help hint
+	servicePath string       // service HTTP base path
+	risk        string       // RiskRead | RiskWrite | RiskHighRiskWrite
+	restricts   bool         // method declares accessTokens (identity-restricted)
+	identities  []string     // permitted --as values; empty when unrestricted
+	params      []meta.Field // path/query params -> typed flags
+	fileFields  []string     // request-body file-upload field names
+	// acceptsBody is whether the HTTP method allows a request body at all (so
+	// --data is offered as a raw escape hatch). declaresBody is whether the
+	// metadata documents body fields (data or file). They differ for e.g. a POST
+	// with no documented requestBody: --data still works, but help must not imply
+	// the API declares a body.
+	acceptsBody  bool
+	declaresBody bool
+	paginates    bool   // method accepts a page_token param (so --page-all is meaningful)
+	serviceName  string // owning service name (e.g. "approval"), for the lazy affordance lookup
+}
+
+// methodPaginates reports whether a method takes a page_token param, the signal
+// that makes the --page-all/--page-limit/--page-delay flags meaningful.
+func methodPaginates(m meta.Method) bool {
+	for _, f := range m.Params() {
+		if f.Name == "page_token" {
+			return true
+		}
+	}
+	return false
+}
+
+func newMethodCommandSpec(ref apicatalog.MethodRef) methodCommandSpec {
+	m := ref.Method
+	return methodCommandSpec{
+		method:       m,
+		schemaPath:   ref.SchemaPath(),
+		servicePath:  ref.Service.ServicePath,
+		serviceName:  ref.Service.Name,
+		risk:         m.Risk,
+		restricts:    m.RestrictsIdentity(),
+		identities:   m.Identities(),
+		params:       m.Params(),
+		fileFields:   detectFileFields(m),
+		acceptsBody:  methodTakesBody(m.HTTPMethod),
+		declaresBody: len(m.Data()) > 0 || len(m.Files()) > 0,
+		paginates:    methodPaginates(m),
+	}
+}
+
+// methodTakesBody reports whether the HTTP method allows a request body, i.e.
+// whether --data applies (as a raw escape hatch even when no body is declared).
+func methodTakesBody(httpMethod string) bool {
+	switch httpMethod {
+	case "POST", "PUT", "PATCH", "DELETE":
+		return true
+	}
+	return false
+}
+
+// buildMethodCommand assembles the cobra command for a service method from its
+// static spec: the standard flags, the conditional --data/--file/--yes flags,
+// the generated typed param flags (via paramFlagBinder), and the risk/identity
+// policy annotations.
+func buildMethodCommand(ctx context.Context, f *cmdutil.Factory, spec methodCommandSpec, runF func(*ServiceMethodOptions) error, reserved *pflag.FlagSet) *cobra.Command {
+	m := spec.method
+	opts := &ServiceMethodOptions{
+		Factory:     f,
+		ServicePath: spec.servicePath,
+		Method:      m,
+		SchemaPath:  spec.schemaPath,
+		FileFields:  spec.fileFields,
+	}
+	var asStr string
+
+	cmd := &cobra.Command{
+		Use:   m.Name,
+		Short: m.Description,
+		// Long is assembled below, once the binder knows which params got no
+		// typed flag.
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts.Cmd = cmd
+			opts.Ctx = cmd.Context()
+			opts.As = core.Identity(asStr)
+			if runF != nil {
+				return runF(opts)
+			}
+			return serviceMethodRun(opts)
+		},
+	}
+	cmdmeta.SetSource(cmd, cmdmeta.SourceService, true)
+
+	cmd.Flags().StringVar(&opts.Params, "params", "", "Raw URL/query params JSON. Supports - and @file.")
+	if spec.acceptsBody {
+		dataUsage := "JSON request body. Supports - and @file."
+		if !spec.declaresBody {
+			// POST/etc. with no documented body fields: --data is a raw escape
+			// hatch, not a declared body — say so rather than imply structure.
+			dataUsage = "Raw JSON request body (no documented fields; see schema). Supports - and @file."
+		}
+		cmd.Flags().StringVar(&opts.Data, "data", "", dataUsage)
+	}
+	cmdutil.AddAPIIdentityFlag(ctx, cmd, f, &asStr)
+	cmd.Flags().StringVarP(&opts.Output, "output", "o", "", "output file path for binary responses")
+	cmd.Flags().BoolVar(&opts.PageAll, "page-all", false, "automatically paginate through all pages")
+	cmd.Flags().IntVar(&opts.PageLimit, "page-limit", 10, "max pages to fetch with --page-all (0 = unlimited)")
+	cmd.Flags().IntVar(&opts.PageDelay, "page-delay", 200, "delay in ms between pages")
+	// Keep the pagination flags registered (a harmless no-op if passed) but hide
+	// them from help on non-paginating commands, so help doesn't imply a
+	// get/write can paginate.
+	if !spec.paginates {
+		for _, name := range []string{"page-all", "page-limit", "page-delay"} {
+			_ = cmd.Flags().MarkHidden(name)
+		}
+	}
+	cmd.Flags().StringVar(&opts.Format, "format", "json", "output format: json|ndjson|table|csv")
+	cmd.Flags().Bool("json", false, "shorthand for --format json")
+	cmd.Flags().StringVarP(&opts.JqExpr, "jq", "q", "", "jq expression to filter JSON output")
+	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "print request without executing")
+	if spec.risk == cmdutil.RiskHighRiskWrite {
+		cmd.Flags().Bool("yes", false, "confirm high-risk operation")
+	}
+	// --file only for body methods that actually declare file-type fields.
+	if len(spec.fileFields) > 0 && spec.acceptsBody {
+		cmd.Flags().StringVar(&opts.File, "file", "", "File upload [field=]path. Supports - and stdin.")
+	}
+	cmdutil.RegisterFlagCompletion(cmd, "format", func(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+		return []string{"json", "ndjson", "table", "csv"}, cobra.ShellCompDirectiveNoFileComp
+	})
+
+	// Registered last so the collision guard sees the standard flags above.
+	opts.binder = newParamFlagBinder(cmd, spec.params, reserved)
+	// Build-time Long; the agent guidance is added lazily by PrepareMethodHelp
+	// (setMethodHelpData records the coordinates it needs).
+	paramsOnly := opts.binder.paramsOnlyHelp()
+	cmd.Long = methodLong(m.Description, spec.schemaPath, paramsOnly)
+	setMethodHelpData(cmd, spec.serviceName, m.ID, spec.schemaPath, paramsOnly)
+
+	// Group flags for the grouped --help renderer (typed param flags are grouped
+	// as API Parameters by the binder). tagFlagGroup is a no-op for flags not
+	// registered above (e.g. --data/--file/--yes only exist for some methods).
+	// --data sits under Request Body only when the metadata documents body
+	// fields; otherwise it's a raw escape hatch, grouped with --params so help
+	// doesn't imply a declared body the API doesn't have.
+	if fl := cmd.Flags().Lookup("data"); fl != nil {
+		if spec.declaresBody {
+			annotate(fl, flagGroupAnnotation, []string{groupBody})
+		} else {
+			annotate(fl, flagGroupAnnotation, []string{groupRaw})
+		}
+	}
+	tagFlagGroup(cmd.Flags(), "file", groupBody)
+	if fl := cmd.Flags().Lookup("params"); fl != nil {
+		annotate(fl, flagGroupAnnotation, []string{groupRaw})
+		// Keep the precedence rule on the flag's own one line (not a multi-line
+		// note that breaks the one-entry-per-flag rhythm an agent parses). Only
+		// meaningful when typed flags exist to override.
+		if len(spec.params) > 0 {
+			fl.Usage = "Raw URL/query params JSON. Supports - and @file. If both set, typed flags override matching keys in --params."
+		}
+	}
+	for _, name := range []string{"as", "dry-run", "page-all", "page-limit", "page-delay", "yes"} {
+		tagFlagGroup(cmd.Flags(), name, groupExecution)
+	}
+	for _, name := range []string{"output", "format", "jq"} {
+		tagFlagGroup(cmd.Flags(), name, groupOutput)
+	}
+	applyGroupedUsage(cmd)
+
+	cmdutil.SetTips(cmd, m.Tips)
+	cmdutil.SetRisk(cmd, spec.risk)
+	if spec.restricts {
+		cmdutil.SetSupportedIdentities(cmd, spec.identities)
+	}
+
+	return cmd
+}
+
+func serviceMethodRun(opts *ServiceMethodOptions) error {
+	f := opts.Factory
+	opts.As = f.ResolveAs(opts.Ctx, opts.Cmd, opts.As)
+
+	if err := f.CheckStrictMode(opts.Ctx, opts.As); err != nil {
+		return err
+	}
+
+	// Check if this API method supports the resolved identity.
+	if opts.Method.RestrictsIdentity() {
+		if err := f.CheckIdentity(opts.As, opts.Method.Identities()); err != nil {
+			return err
+		}
+	}
+
+	if opts.PageAll && opts.Output != "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--output and --page-all are mutually exclusive").WithParam("--output")
+	}
+	if err := output.ValidateJqFlags(opts.JqExpr, opts.Output, opts.Format); err != nil {
+		return err
+	}
+
+	config, err := f.Config()
+	if err != nil {
+		return err
+	}
+	// Identity is not printed to stderr here: it is part of the JSON envelope.
+
+	if !opts.As.IsBot() {
+		if err := checkServiceScopes(opts.Ctx, f.Credential, opts.As, config, opts.Method); err != nil {
+			return err
+		}
+	}
+
+	request, fileMeta, err := buildServiceRequest(opts)
+	if err != nil {
+		return err
+	}
+
+	if opts.DryRun {
+		if fileMeta != nil {
+			return cmdutil.PrintDryRunWithFile(f.IOStreams.Out, request, config, opts.Format, fileMeta.FieldName, fileMeta.FilePath, fileMeta.FormFields)
+		}
+		return serviceDryRun(f, request, config, opts.Format)
+	}
+
+	if opts.Method.Risk == cmdutil.RiskHighRiskWrite {
+		if yes, _ := opts.Cmd.Flags().GetBool("yes"); !yes {
+			return cmdutil.RequireConfirmation(opts.SchemaPath)
+		}
+	}
+
+	ac, err := f.NewAPIClientWithConfig(config)
+	if err != nil {
+		return err
+	}
+
+	out := f.IOStreams.Out
+	format, formatOK := output.ParseFormat(opts.Format)
+	if !formatOK {
+		fmt.Fprintf(f.IOStreams.ErrOut, "warning: unknown format %q, falling back to json\n", opts.Format)
+	}
+
+	// Scope-insufficient (99991679) and all other Lark API codes route through
+	// errclass.BuildAPIError via ac.CheckResponse, producing *errs.PermissionError
+	// with MissingScopes / Identity / ConsoleURL populated from the response.
+	checkErr := ac.CheckResponse
+
+	if opts.PageAll {
+		return servicePaginate(opts.Ctx, ac, request, format, opts.JqExpr, out, f.IOStreams.ErrOut, opts.Cmd.CommandPath(),
+			client.PaginationOptions{PageLimit: opts.PageLimit, PageDelay: opts.PageDelay}, checkErr)
+	}
+
+	resp, err := ac.DoAPI(opts.Ctx, request)
+	if err != nil {
+		return err
+	}
+	return client.HandleResponse(resp, client.ResponseOptions{
+		OutputPath:  opts.Output,
+		Format:      format,
+		JqExpr:      opts.JqExpr,
+		Out:         out,
+		ErrOut:      f.IOStreams.ErrOut,
+		FileIO:      f.ResolveFileIO(opts.Ctx),
+		CommandPath: opts.Cmd.CommandPath(),
+		Identity:    opts.As,
+		CheckError:  checkErr,
+	})
+}
+
+// checkServiceScopes pre-checks user scopes before making the API call.
+func checkServiceScopes(ctx context.Context, cred *credential.CredentialProvider, identity core.Identity, config *core.CliConfig, method meta.Method) error {
+	if ctx.Err() != nil {
+		return ctx.Err()
+	}
+	result, err := cred.ResolveToken(ctx, credential.NewTokenSpec(identity, config.AppID))
+	if err != nil || result == nil || result.Scopes == "" {
+		return nil //nolint:nilerr // skip scope check when token resolution fails or has no scopes
+	}
+
+	if len(method.RequiredScopes) > 0 {
+		// Strict: ALL requiredScopes must be present
+		if missing := auth.MissingScopes(result.Scopes, method.RequiredScopes); len(missing) > 0 {
+			return newPreflightMissingScopeError(string(config.Brand), config.AppID, string(identity), missing)
+		}
+		return nil
+	}
+
+	if len(method.Scopes) == 0 {
+		return nil
+	}
+
+	// Default: ANY one of the declared scopes is sufficient
+	grantedSet := make(map[string]bool)
+	for _, s := range strings.Fields(result.Scopes) {
+		grantedSet[s] = true
+	}
+	for _, s := range method.Scopes {
+		if grantedSet[s] {
+			return nil
+		}
+	}
+	recommended := registry.SelectRecommendedScopeFromStrings(method.Scopes, "user")
+	return newPreflightMissingScopeError(string(config.Brand), config.AppID, string(identity), []string{recommended})
+}
+
+// newPreflightMissingScopeError constructs a PermissionError for the local
+// pre-flight scope check that converges byte-for-byte with the dispatcher's
+// BuildAPIError path. Uses the canonical helpers in internal/errclass so
+// Hint and Message stay in lock-step with the server-response classifier.
+// ConsoleURL is deliberately omitted: the dispatcher only sets it for
+// SubtypeAppScopeNotApplied (bot-perspective dev-action recovery), and this
+// pre-flight path is user-perspective SubtypeMissingScope whose recovery is
+// `lark-cli auth login --scope ...`, not a console deep-link.
+func newPreflightMissingScopeError(brand, appID, identity string, missing []string) *errs.PermissionError {
+	consoleURL := errclass.ConsoleURL(brand, appID, missing)
+	return errs.NewPermissionError(errs.SubtypeMissingScope,
+		"%s", errclass.CanonicalPermissionMessage(errs.SubtypeMissingScope, appID, missing, "")).
+		WithHint("%s", errclass.PermissionHint(missing, identity, errs.SubtypeMissingScope, consoleURL)).
+		WithMissingScopes(missing...).
+		WithIdentity(identity)
+}
+
+// unusableParamValue reports whether a provided path/query parameter value
+// cannot form a usable request value: nil or an empty string. A key's presence
+// in params is the intent signal — a typed flag is overlaid only when
+// explicitly Changed, and a --params JSON key is deliberately written — so
+// false and 0 are real values and must not be conflated with "unset"
+// (reflect.IsZero would drop an explicit --with-deleted=false or --foo 0).
+// Only nil/"" stay treated as missing: that keeps the friendly pre-flight
+// error when a required param is fed an empty placeholder, and never emits a
+// declared param as an empty path segment or query value. Undeclared keys are
+// not judged by this rule — they pass through verbatim as the raw escape hatch.
+func unusableParamValue(v interface{}) bool {
+	if v == nil {
+		return true
+	}
+	s, ok := v.(string)
+	return ok && s == ""
+}
+
+// missingParamHint is the recovery hint for a missing required parameter. It
+// names both input paths — the typed flag when the binder registered one, and
+// the --params fallback — plus the schema pointer. A params-only field gets
+// only the --params form: a flag with its kebab name exists but belongs to
+// something else (e.g. the output --format), and the hint must not steer
+// there. Asking the binder, not cmd.Flags(), is what tells those apart.
+func missingParamHint(opts *ServiceMethodOptions, f meta.Field) string {
+	paramsForm := fmt.Sprintf("--params '{%q: \"<value>\"}'", f.Name)
+	if opts.binder.hasTypedFlag(f.Name) {
+		return fmt.Sprintf("set --%s <value> (or %s); see: lark-cli schema %s", f.FlagName(), paramsForm, opts.SchemaPath)
+	}
+	return fmt.Sprintf("set %s; see: lark-cli schema %s", paramsForm, opts.SchemaPath)
+}
+
+// buildServiceRequest parses flags, builds the URL with path/query params, and returns a RawApiRequest.
+// When dryRun is true and a file is provided, file reading is skipped and
+// FileUploadMeta is returned instead so the caller can render dry-run output.
+func buildServiceRequest(opts *ServiceMethodOptions) (client.RawApiRequest, *cmdutil.FileUploadMeta, error) {
+	method := opts.Method
+	httpMethod := method.HTTPMethod
+
+	// stdin is an io.Reader consumed at most once. Only one of --params/--data
+	// may use "-" (stdin); the conflict check below prevents silent data loss.
+	stdin := opts.Factory.IOStreams.In
+	fileIO := opts.Factory.ResolveFileIO(opts.Ctx)
+
+	// Validate --file mutual exclusions.
+	if err := cmdutil.ValidateFileFlag(opts.File, opts.Params, opts.Data, opts.Output, opts.PageAll, httpMethod); err != nil {
+		return client.RawApiRequest{}, nil, err
+	}
+	if opts.Params == "-" && opts.Data == "-" {
+		return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--params and --data cannot both read from stdin (-)").WithParam("--params")
+	}
+	params, err := cmdutil.ParseJSONMap(opts.Params, "--params", stdin, fileIO)
+	if err != nil {
+		return client.RawApiRequest{}, nil, err
+	}
+	opts.binder.overlay(opts.Cmd, params)
+
+	url := opts.ServicePath + "/" + method.Path
+
+	specs := method.Params()
+	for _, s := range specs {
+		if s.Location != "path" {
+			continue
+		}
+		val, ok := params[s.Name]
+		if !ok || unusableParamValue(val) {
+			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"missing required path parameter: %s", s.Name).
+				WithHint("%s", missingParamHint(opts, s)).
+				WithParam(s.Name)
+		}
+		valStr := fmt.Sprintf("%v", val)
+		if err := validate.ResourceName(valStr, s.Name); err != nil {
+			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam(s.Name).WithCause(err)
+		}
+		url = strings.Replace(url, "{"+s.Name+"}", validate.EncodePathSegment(valStr), 1)
+		delete(params, s.Name)
+	}
+
+	queryParams := map[string]interface{}{}
+	for _, s := range specs {
+		if s.Location != "query" {
+			continue
+		}
+		value, exists := params[s.Name]
+		isPaginationParam := opts.PageAll && (s.Name == "page_token" || s.Name == "page_size")
+		if s.Required && !isPaginationParam && (!exists || unusableParamValue(value)) {
+			return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
+				"missing required query parameter: %s", s.Name).
+				WithHint("%s", missingParamHint(opts, s)).
+				WithParam(s.Name)
+		}
+		if exists && !unusableParamValue(value) {
+			queryParams[s.Name] = value
+		}
+		// This loop owns declared query params: consume the key so the
+		// passthrough below can't resurrect a value the gate dropped (an
+		// unusable "" would otherwise be sent as an empty query value).
+		delete(params, s.Name)
+	}
+	// Whatever remains is undeclared — the raw escape hatch for params the
+	// metadata doesn't (yet) describe; passed through verbatim, no filtering.
+	for name, value := range params {
+		queryParams[name] = value
+	}
+
+	request := client.RawApiRequest{
+		Method: httpMethod,
+		URL:    url,
+		Params: queryParams,
+		As:     opts.As,
+	}
+
+	if opts.File != "" {
+		// File upload: determine default field name from metadata.
+		defaultField := "file"
+		if len(opts.FileFields) == 1 {
+			defaultField = opts.FileFields[0]
+		}
+		fieldName, filePath, isStdin := cmdutil.ParseFileFlag(opts.File, defaultField)
+
+		// Parse --data as form fields.
+		var dataFields any
+		if opts.Data != "" {
+			dataFields, err = cmdutil.ParseOptionalBody(httpMethod, opts.Data, stdin, fileIO)
+			if err != nil {
+				return client.RawApiRequest{}, nil, err
+			}
+			if _, ok := dataFields.(map[string]any); !ok {
+				return client.RawApiRequest{}, nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--data must be a JSON object when used with --file").WithParam("--data")
+			}
+		}
+
+		if opts.DryRun {
+			return request, &cmdutil.FileUploadMeta{
+				FieldName: fieldName, FilePath: filePath, FormFields: dataFields,
+			}, nil
+		}
+
+		fd, err := cmdutil.BuildFormdata(
+			fileIO,
+			fieldName, filePath, isStdin, stdin, dataFields,
+		)
+		if err != nil {
+			return client.RawApiRequest{}, nil, err
+		}
+		request.Data = fd
+		request.ExtraOpts = append(request.ExtraOpts, larkcore.WithFileUpload())
+	} else {
+		data, err := cmdutil.ParseOptionalBody(httpMethod, opts.Data, stdin, fileIO)
+		if err != nil {
+			return client.RawApiRequest{}, nil, err
+		}
+		request.Data = data
+		if opts.Output != "" {
+			request.ExtraOpts = append(request.ExtraOpts, larkcore.WithFileDownload())
+		}
+	}
+
+	return request, nil, nil
+}
+
+func serviceDryRun(f *cmdutil.Factory, request client.RawApiRequest, config *core.CliConfig, format string) error {
+	return cmdutil.PrintDryRun(f.IOStreams.Out, request, config, format)
+}
+
+func servicePaginate(ctx context.Context, ac *client.APIClient, request client.RawApiRequest, format output.Format, jqExpr string, out, errOut io.Writer, commandPath string, pagOpts client.PaginationOptions, checkErr func(interface{}, core.Identity) error) error {
+	if pagOpts.Identity == "" {
+		pagOpts.Identity = request.As
+	}
+	// When jq is set, always aggregate all pages then filter.
+	if jqExpr != "" {
+		result, err := ac.PaginateAll(ctx, request, pagOpts)
+		if err != nil {
+			return err
+		}
+		if apiErr := checkErr(result, pagOpts.Identity); apiErr != nil {
+			output.FormatValue(out, result, output.FormatJSON)
+			return apiErr
+		}
+		return output.WriteSuccessEnvelope(output.SuccessEnvelopeData(result), output.SuccessEnvelopeOptions{
+			CommandPath: commandPath,
+			Identity:    string(pagOpts.Identity),
+			JqExpr:      jqExpr,
+			Out:         out,
+			ErrOut:      errOut,
+		})
+	}
+
+	switch format {
+	case output.FormatNDJSON, output.FormatTable, output.FormatCSV:
+		pf := output.NewPaginatedFormatter(out, format)
+		result, hasItems, err := ac.StreamPages(ctx, request, func(items []interface{}) error {
+			// Streaming formats intentionally emit each page after that page has
+			// passed safety scanning. A later page may still fail, so callers
+			// must use the exit code to distinguish complete vs partial output.
+			scanResult := output.ScanForSafety(commandPath, items, errOut)
+			if scanResult.Blocked {
+				return scanResult.BlockErr
+			}
+			if scanResult.Alert != nil {
+				output.WriteAlertWarning(errOut, scanResult.Alert)
+			}
+			pf.FormatPage(items)
+			return nil
+		}, pagOpts)
+		if err != nil {
+			return err
+		}
+		if apiErr := checkErr(result, pagOpts.Identity); apiErr != nil {
+			return apiErr
+		}
+		if !hasItems {
+			fmt.Fprintf(errOut, "warning: this API does not return a list, format %q is not supported, falling back to json\n", format)
+			return output.WriteSuccessEnvelope(output.SuccessEnvelopeData(result), output.SuccessEnvelopeOptions{
+				CommandPath: commandPath,
+				Identity:    string(pagOpts.Identity),
+				Out:         out,
+				ErrOut:      errOut,
+			})
+		}
+		return nil
+	default:
+		result, err := ac.PaginateAll(ctx, request, pagOpts)
+		if err != nil {
+			return err
+		}
+		if apiErr := checkErr(result, pagOpts.Identity); apiErr != nil {
+			output.FormatValue(out, result, output.FormatJSON)
+			return apiErr
+		}
+		return output.WriteSuccessEnvelope(output.SuccessEnvelopeData(result), output.SuccessEnvelopeOptions{
+			CommandPath: commandPath,
+			Identity:    string(pagOpts.Identity),
+			Out:         out,
+			ErrOut:      errOut,
+		})
+	}
+}

cmd/service/service_risk_test.go

@@ -0,0 +1,115 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package service
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/meta"
+)
+
+// highRiskDeleteMethod mirrors a simple DELETE API with a required path
+// parameter and risk metadata. The test exercises --yes registration and the
+// gate behavior.
+func highRiskDeleteMethod() meta.Method {
+	return meta.FromMap(map[string]interface{}{
+		"path":       "files/{file_token}",
+		"httpMethod": "DELETE",
+		"risk":       "high-risk-write",
+		"parameters": map[string]interface{}{
+			"file_token": map[string]interface{}{
+				"type": "string", "location": "path", "required": true,
+			},
+		},
+	})
+}
+
+func writeMethodNoRisk() meta.Method {
+	return meta.FromMap(map[string]interface{}{
+		"path":       "files/{file_token}",
+		"httpMethod": "DELETE",
+		"parameters": map[string]interface{}{
+			"file_token": map[string]interface{}{
+				"type": "string", "location": "path", "required": true,
+			},
+		},
+	})
+}
+
+func TestServiceMethod_YesFlagRegisteredForHighRisk(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, driveSpec(), highRiskDeleteMethod(), "delete", "files", nil)
+
+	if cmd.Flags().Lookup("yes") == nil {
+		t.Error("expected --yes flag registered for risk=high-risk-write")
+	}
+}
+
+func TestServiceMethod_YesFlagNotRegisteredForWrite(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, driveSpec(), writeMethodNoRisk(), "delete", "files", nil)
+
+	if cmd.Flags().Lookup("yes") != nil {
+		t.Error("expected --yes flag NOT registered when risk is unset")
+	}
+}
+
+func TestServiceMethod_RiskAnnotationSet(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, driveSpec(), highRiskDeleteMethod(), "delete", "files", nil)
+
+	level, ok := cmdutil.GetRisk(cmd)
+	if !ok {
+		t.Fatal("expected Risk annotation to be set")
+	}
+	if level != "high-risk-write" {
+		t.Errorf("level = %q, want high-risk-write", level)
+	}
+}
+
+func TestServiceMethod_RiskAnnotationAbsentForUnsetRisk(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, driveSpec(), writeMethodNoRisk(), "delete", "files", nil)
+
+	if _, ok := cmdutil.GetRisk(cmd); ok {
+		t.Error("expected no Risk annotation when meta risk is unset")
+	}
+}
+
+func TestServiceMethod_GateBlocksWithoutYes(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, driveSpec(), highRiskDeleteMethod(), "delete", "files", nil)
+	// --as bot skips the scope check so we reach the gate without external creds.
+	cmd.SetArgs([]string{"--as", "bot", "--params", `{"file_token":"tok_abc"}`})
+
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatal("expected confirmation error, got nil")
+	}
+	if !strings.Contains(err.Error(), "requires confirmation") {
+		t.Errorf("expected 'requires confirmation' in error, got: %v", err)
+	}
+	if !strings.Contains(err.Error(), "drive.files.delete") {
+		t.Errorf("expected schema path in error action, got: %v", err)
+	}
+}
+
+func TestServiceMethod_DryRunBypassesGate(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, testConfig)
+	cmd := NewCmdServiceMethod(f, driveSpec(), highRiskDeleteMethod(), "delete", "files", nil)
+	cmd.SetArgs([]string{
+		"--as", "bot",
+		"--params", `{"file_token":"tok_abc"}`,
+		"--dry-run",
+	})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("dry-run should not hit confirmation gate; got: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "files/tok_abc") {
+		t.Errorf("expected dry-run output to contain URL, got:\n%s", stdout.String())
+	}
+}