docs: optimize base skill references

Author: zgz2048

cmd/service/service.go

@@ -181,7 +181,7 @@ func NewCmdServiceMethodWithContext(ctx context.Context, f *cmdutil.Factory, spe
 	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 risk == "high-risk-write" {
-		cmd.Flags().Bool("yes", false, "confirm high-risk operation")
+		cmd.Flags().Bool("yes", false, cmdutil.HighRiskYesFlagHelp)
 	}
 
 	// Conditionally register --file for methods with file-type fields.

cmd/service/service_risk_test.go

@@ -42,9 +42,13 @@ 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 {
+	flag := cmd.Flags().Lookup("yes")
+	if flag == nil {
 		t.Error("expected --yes flag registered for risk=high-risk-write")
 	}
+	if !strings.Contains(flag.Usage, "pass --yes without asking again") {
+		t.Fatalf("--yes help missing agent guidance: %q", flag.Usage)
+	}
 }
 
 func TestServiceMethod_YesFlagNotRegisteredForWrite(t *testing.T) {

internal/cmdutil/confirm.go

@@ -9,6 +9,8 @@ import (
 	"github.com/larksuite/cli/internal/output"
 )
 
+const HighRiskYesFlagHelp = "confirm high-risk operation; if the user explicitly requested it and the target is unambiguous, pass --yes without asking again"
+
 // RequireConfirmation constructs a confirmation_required error with exit code
 // ExitConfirmationRequired and a structured Risk envelope. Used by both
 // shortcut and service command execution paths when a statically

shortcuts/base/base_advperm_disable.go

@@ -25,6 +25,9 @@ var BaseAdvpermDisable = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "base token", Required: true},
 	},
+	Tips: []string{
+		"Disabling advanced permissions invalidates existing custom roles; confirm the target Base before passing --yes.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
 			return common.FlagErrorf("--base-token must not be blank")

shortcuts/base/base_copy.go

@@ -24,6 +24,11 @@ var BaseBaseCopy = common.Shortcut{
 		{Name: "without-content", Type: "bool", Desc: "copy structure only"},
 		{Name: "time-zone", Desc: "time zone, e.g. Asia/Shanghai"},
 	},
+	Tips: []string{
+		`Example: lark-cli base +base-copy --base-token <base_token> --name "Copy of Project Tracker"`,
+		"Use --without-content when the user wants only structure.",
+		"If copied as bot, output may include permission_grant; report it so the user knows whether they can open the new Base.",
+	},
 	DryRun: dryRunBaseCopy,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeBaseCopy(runtime)

shortcuts/base/base_create.go

@@ -22,6 +22,10 @@ var BaseBaseCreate = common.Shortcut{
 		{Name: "folder-token", Desc: "folder token for destination"},
 		{Name: "time-zone", Desc: "time zone, e.g. Asia/Shanghai"},
 	},
+	Tips: []string{
+		`Example: lark-cli base +base-create --name "Project Tracker" --time-zone Asia/Shanghai`,
+		"If created as bot, output may include permission_grant; report it so the user knows whether they can open the new Base.",
+	},
 	DryRun: dryRunBaseCreate,
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		return executeBaseCreate(runtime)

shortcuts/base/base_execute_test.go

@@ -515,7 +515,7 @@ func TestBaseObjectJSONShortcutsRejectArrayInDryRun(t *testing.T) {
 			if !strings.Contains(err.Error(), "--json must be a JSON object") {
 				t.Fatalf("err=%v", err)
 			}
-			if !strings.Contains(err.Error(), "lark-base skill") {
+			if !strings.Contains(err.Error(), "match the documented shape") {
 				t.Fatalf("err=%v", err)
 			}
 			if strings.Contains(err.Error(), "array") {

shortcuts/base/base_form_list.go

@@ -23,7 +23,7 @@ var BaseFormsList = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "base-token", Desc: "Base token (base_token)", Required: true},
 		{Name: "table-id", Desc: "table ID", Required: true},
-		{Name: "page-size", Type: "int", Default: "100", Desc: "page size per request (max 100)"},
+		{Name: "page-size", Type: "int", Default: "100", Desc: "page size per request, max 100"},
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		return common.NewDryRunAPI().

shortcuts/base/base_role_create.go

@@ -27,6 +27,11 @@ var BaseRoleCreate = common.Shortcut{
 		{Name: "base-token", Desc: "base token", Required: true},
 		{Name: "json", Desc: `body JSON (AdvPermBaseRoleConfig), e.g. {"role_name":"Reviewer","role_type":"custom_role","table_rule_map":{...}}`, Required: true},
 	},
+	Tips: []string{
+		`Example: --json '{"role_name":"Reviewer","role_type":"custom_role","base_rule_map":{"copy":false,"download":false}}'`,
+		"Read role-config.md for table_rule_map, dashboard_rule_map, docx_rule_map, and filter permission JSON.",
+		"Create supports custom_role only.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
 			return common.FlagErrorf("--base-token must not be blank")

shortcuts/base/base_role_delete.go

@@ -26,6 +26,10 @@ var BaseRoleDelete = common.Shortcut{
 		{Name: "base-token", Desc: "base token", Required: true},
 		{Name: "role-id", Desc: "role ID (e.g. rolxxxxxx4)", Required: true},
 	},
+	Tips: []string{
+		"Only custom roles can be deleted; system roles cannot be deleted.",
+		"Use +role-get first if the role target is ambiguous, then pass --yes to confirm deletion.",
+	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if strings.TrimSpace(runtime.Str("base-token")) == "" {
 			return common.FlagErrorf("--base-token must not be blank")