From 2e4033a1a071acdb599dd83bc162d3ee459fbe1c Mon Sep 17 00:00:00 2001
From: xiongyuanwen-byted <xiongyuanwen@bytedance.com>
Date: Wed, 17 Jun 2026 11:35:37 +0800
Subject: [PATCH] fix(shortcuts): clarify single-stdin constraint in flag help
 and error hint

Input flags advertised '(supports @file, - for stdin)' per flag, leading
AI agents to write '--a - <x --b - <y' where the second '<' silently
clobbers the first and the first flag reads the wrong payload. A process
has a single stdin, so at most one flag per call can use '-'.

- Reword the generated help hint to '- reads stdin (one flag per call;
  use @file for others)'.
- Add an actionable .WithHint to the stdin-conflict validation error
  pointing callers to @file for the extra flags.
- Assert the new hint in TestResolveInputFlags_DuplicateStdin.
---
 shortcuts/common/runner.go            | 11 +++++++++--
 shortcuts/common/runner_input_test.go |  7 ++++++-
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/shortcuts/common/runner.go b/shortcuts/common/runner.go
index d8be762cd..a6b9cf157 100644
--- a/shortcuts/common/runner.go
+++ b/shortcuts/common/runner.go
@@ -1147,7 +1147,8 @@ func resolveInputFlags(rctx *RuntimeContext, flags []Flag) error {
 			}
 			if stdinUsed {
 				return ValidationErrorf("--%s: stdin (-) can only be used by one flag", fl.Name).
-					WithParam("--" + fl.Name)
+					WithParam("--"+fl.Name).
+					WithHint("a process has a single stdin, so only one flag per call may use '-'; pass the others as @file (e.g. --%s @/path/to/file)", fl.Name)
 			}
 			stdinUsed = true
 			data, err := io.ReadAll(rctx.IO().In)
@@ -1262,7 +1263,13 @@ func registerShortcutFlagsWithContext(ctx context.Context, cmd *cobra.Command, f
 				hints = append(hints, "@file")
 			}
 			if slices.Contains(fl.Input, Stdin) {
-				hints = append(hints, "- for stdin")
+				// "- reads stdin" intentionally avoids implying each flag has
+				// its own stdin: a process has a single stdin, so at most one
+				// flag per call may use "-" (the rest must use @file). The old
+				// per-flag "- for stdin" wording led AI agents to write
+				// `--a - <x --b - <y`, where the second `<` silently clobbers
+				// the first and `--a` reads the wrong payload.
+				hints = append(hints, "- reads stdin (one flag per call; use @file for others)")
 			}
 			desc += " (supports " + strings.Join(hints, ", ") + ")"
 		}
diff --git a/shortcuts/common/runner_input_test.go b/shortcuts/common/runner_input_test.go
index 1b46dda1e..377abc2b3 100644
--- a/shortcuts/common/runner_input_test.go
+++ b/shortcuts/common/runner_input_test.go
@@ -216,10 +216,15 @@ func TestResolveInputFlags_DuplicateStdin(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected error for duplicate stdin usage")
 	}
-	assertValidationParam(t, err, "--b")
+	vErr := assertValidationParam(t, err, "--b")
 	if !strings.Contains(err.Error(), "stdin (-) can only be used by one flag") {
 		t.Errorf("unexpected error: %v", err)
 	}
+	// The hint must steer an AI agent to the fix (@file for the extra flags),
+	// since `--a - <x --b - <y` is the exact misuse this guards against.
+	if !strings.Contains(vErr.Hint, "@file") {
+		t.Errorf("hint %q should mention @file as the fix", vErr.Hint)
+	}
 }
 
 func TestStripUTF8BOM(t *testing.T) {