Merge pull request #2736 from pikasTech/fix/2721-release-help-next

fix(cicd): 补齐手动发布帮助与 next 指引

.agents/skills/unidesk-cicd/SKILL.md

@@ -74,6 +74,7 @@ bun scripts/cli.ts hwlab nodes control-plane legacy-cicd --help
   - 审阅通过后运行 `release trigger --confirm`；该命令只向 PaC 发送 webhook，由 PaC 创建 PipelineRun；
   - 禁止裸创建 PipelineRun、由 CLI 直建 PipelineRun，或恢复 Gitea 自动 hook；
   - L3 继续要求对应 L2 已通过和用户对当次生产发布的明确授权。
+  - 每次修改发布入口后，必须复核 `pipelines-as-code --help`、`release --help`、`release plan --help`、`release trigger --help` 与一条动态 `next`：帮助必须完整展示 plan/trigger 的参数、范围审阅字段和 `--confirm` 边界；动态 `next` 只能在范围准确时指向 trigger，范围扩大或触发失败时必须指向修复后重新 plan，不得遗漏或引导自动交付。
 
 - 节点级只读状态：
   - 优先用 `cicd status --node <NODE>`；

scripts/src/platform-infra-pipelines-as-code-bootstrap.test.ts

@@ -305,6 +305,19 @@ test("L2/L3 release exposes plan first and trigger only sends the PaC webhook",
   expect(triggerAction).not.toContain("PipelineRun");
 });
 
+test("PaC release scoped help stays on the manual plan-before-trigger path", async () => {
+  const release = await runPlatformInfraPipelinesAsCodeCommand({} as never, ["release", "--help"]);
+  const plan = await runPlatformInfraPipelinesAsCodeCommand({} as never, ["release", "plan", "--help"]);
+  const trigger = await runPlatformInfraPipelinesAsCodeCommand({} as never, ["release", "trigger", "--help"]);
+  expect(release).toMatchObject({ command: "platform-infra pipelines-as-code release", mutation: false });
+  expect(JSON.stringify(release)).toContain("scopeReview.status=exact");
+  expect(JSON.stringify(plan)).toContain("release plan --target <NODE>");
+  expect(JSON.stringify(plan)).toContain("envReuse");
+  expect(JSON.stringify(trigger)).toContain("release trigger --target <NODE>");
+  expect(JSON.stringify(trigger)).toContain("--confirm");
+  expect(JSON.stringify(trigger)).toContain("先执行 release plan");
+});
+
 test("PaC release manifest renders YAML-owned watcher startup backlog probes", () => {
   const pac = readPacConfig({ consumerId: "hwlab-nc01-v03", selectDefault: true });
   const source = readFileSync(resolve(import.meta.dir, "fixtures/pac/release-leading-comment-only.yaml"), "utf8");

scripts/src/platform-infra-pipelines-as-code.ts

@@ -363,7 +363,9 @@ export async function runPlatformInfraPipelinesAsCodeCommand(config: UniDeskConf
   }
   if (action === "release") {
     const releaseAction = args[1];
+    if (releaseAction === undefined || releaseAction === "--help" || releaseAction === "-h") return help("release");
     if (releaseAction !== "plan" && releaseAction !== "trigger") return { ok: false, action: "platform-infra-pipelines-as-code-release", mutation: false, error: "unsupported-release-action", usage: "pipelines-as-code release plan|trigger --target <NODE> --consumer <consumer> --source-commit <sha> [--base-commit <sha>] [--confirm]", valuesPrinted: false };
+    if (args.slice(2).includes("--help") || args.slice(2).includes("-h")) return help(`release-${releaseAction}`);
     const options = parseManualReleaseOptions(args.slice(2));
     if (releaseAction === "plan" && options.confirm) throw new Error("release plan does not accept --confirm");
     if (releaseAction === "trigger" && !options.confirm) throw new Error("release trigger requires --confirm after reviewing release plan");
@@ -568,6 +570,23 @@ function sourceArtifactValidationError(error: ReturnType<typeof pacSourceArtifac
 }
 
 function help(scope: string | null): Record<string, unknown> {
+  if (scope === "release" || scope === "release-plan" || scope === "release-trigger") {
+    const action = scope === "release-plan" ? "plan" : scope === "release-trigger" ? "trigger" : null;
+    const planUsage = "bun scripts/cli.ts platform-infra pipelines-as-code release plan --target <NODE> --consumer <consumer> --source-commit <40-sha> [--base-commit <40-sha>]";
+    const triggerUsage = "bun scripts/cli.ts platform-infra pipelines-as-code release trigger --target <NODE> --consumer <consumer> --source-commit <40-sha> [--base-commit <40-sha>] --confirm";
+    return {
+      command: `platform-infra pipelines-as-code release${action === null ? "" : ` ${action}`}`,
+      configTruth: configLabel,
+      usage: action === "plan" ? [planUsage] : action === "trigger" ? [triggerUsage] : [planUsage, triggerUsage],
+      boundary: "PR merge 只更新 source authority，不创建 PipelineRun。必须先 plan；仅当 scopeReview.status=exact 时才可 trigger。trigger 只发送 PaC webhook，由 PaC 创建 PipelineRun。",
+      review: ["requestedScope", "effective", "envReuse", "imageBuildCount", "rolloutServiceCount", "affectedServiceCount", "scopeReview"],
+      next: action === "trigger"
+        ? "先执行 release plan，并确认 scopeReview.status=exact；范围扩大时修复 source range、planner、源码或 owning YAML 后重新 plan。"
+        : "先执行 release plan；仅在 scopeReview.status=exact 时执行 release trigger --confirm。",
+      mutation: action === "trigger" ? "explicit-confirm-required" : false,
+      valuesPrinted: false,
+    };
+  }
   if (scope === "platform-bootstrap") {
     return {
       command: "platform-infra pipelines-as-code help platform-bootstrap",