refactor(flags): keyed type-inferred flag schema; option→flag rename

Replace the positional `OptionDef[]` array (key/type regex-parsed from
"--x <v>" strings) with a keyed `FlagsDef` record whose `type` drives both
runtime parsing and compile-time flag-type inference (`Flags<typeof DEF>`).
GLOBAL_FLAGS becomes the single source; the hand-kept GlobalFlags interface
(types/flags.ts) is deleted.

- core: SwitchFlag|ValueFlag union, ParsedFlags/Flags inference, defineCommand
  infers F from spec.flags
- runtime: parseFlags dispatches on def.type (switch/string/number/boolean/
  array/choices) with declarative required-flag enforcement
- commands: migrate every flag declaration to the keyed form
- naming: option→flag throughout (OptionDef→FlagDef, OptionsDef→FlagsDef,
  GLOBAL_OPTIONS→GLOBAL_FLAGS, command field options→flags), plus user-facing
  "Options:"→"Flags:" in help and the regenerated skill reference docs

Behavior-preserving aside from the intentional Options→Flags wording:
vp check clean across all packages, 29 parser tests pass, reference regen
byte-identical before the terminology swap.

Author: XXPermanentXX

packages/cli/src/commands.ts

@@ -1,4 +1,4 @@
-import type { Command } from "bailian-cli-core";
+import type { AnyCommand } from "bailian-cli-core";
 import {
   authLogin,
   authStatus,
@@ -52,7 +52,7 @@ import {
 // ships no presets, so the map is spelled out here. Kept in its own module
 // (no side effects) so tools like generate-reference.ts can import it without
 // starting the CLI.
-export const commands: Record<string, Command> = {
+export const commands: Record<string, AnyCommand> = {
   "auth login": authLogin,
   "auth status": authStatus,
   "auth logout": authLogout,

packages/commands/src/commands/advisor/recommend.ts

@@ -1,11 +1,9 @@
 import {
   analyzeIntent,
   buildDocLink,
-  type Config,
   defineCommand,
   detectOutputFormat,
   type GetModelsOptions,
-  type GlobalFlags,
   getModels,
   type IntentProfile,
   type PipelineStep,
@@ -217,22 +215,23 @@ export default defineCommand({
     "Recommend the best models for your use case (intent analysis → candidate recall → LLM ranking)",
   auth: "apiKey",
   usageArgs: "--message <text> [flags]",
-  options: [
-    {
-      flag: "--message <text>",
+  flags: {
+    message: {
+      type: "string",
+      valueHint: "<text>",
       description: "Describe your requirements",
       required: true,
     },
-  ],
+  },
   exampleArgs: [
     '--message "I need a visual-understanding chatbot"',
     '--message "Build an Agent that auto-generates animations"',
     '--message "Legal contract review, high precision required"',
     '--message "Low-cost high-concurrency online customer service" --output json',
     '--message "Long document summarization" --dry-run',
   ],
-  async run(config: Config, flags: GlobalFlags) {
-    const userInput = flags.message as string;
+  async run(config, flags) {
+    const userInput = flags.message;
 
     const top = 3;
     const format = detectOutputFormat(config.output);

packages/commands/src/commands/app/call.ts

@@ -5,8 +5,6 @@ import {
   appCompletionEndpoint,
   parseSSE,
   detectOutputFormat,
-  type Config,
-  type GlobalFlags,
   type AppCompletionRequest,
   type AppStreamChunk,
   type AppCompletionResponse,
@@ -17,22 +15,48 @@ export default defineCommand({
   description: "Call a Bailian application (agent or workflow)",
   auth: "apiKey",
   usageArgs: "--app-id <id> --prompt <text> [flags]",
-  options: [
-    { flag: "--app-id <id>", description: "Application ID (required)", required: true },
-    { flag: "--prompt <text>", description: "Input prompt text", required: true },
-    {
-      flag: "--image <url>",
+  flags: {
+    appId: {
+      type: "string",
+      valueHint: "<id>",
+      description: "Application ID (required)",
+      required: true,
+    },
+    prompt: {
+      type: "string",
+      valueHint: "<text>",
+      description: "Input prompt text",
+      required: true,
+    },
+    image: {
+      type: "array",
+      valueHint: "<url>",
       description: "Image URL(s) to pass to the app (repeatable)",
+    },
+    fileId: {
       type: "array",
+      valueHint: "<id>",
+      description: "Pre-uploaded file ID(s) (repeatable)",
     },
-    { flag: "--file-id <id>", description: "Pre-uploaded file ID(s) (repeatable)", type: "array" },
-    { flag: "--session-id <id>", description: "Session ID for multi-turn conversation" },
-    { flag: "--stream", description: "Stream response (default: on in TTY)" },
-    { flag: "--pipeline-ids <ids>", description: "Knowledge base pipeline IDs (comma-separated)" },
-    { flag: "--memory-id <id>", description: "Memory ID for long-term memory" },
-    { flag: "--biz-params <json>", description: "Business parameters JSON (workflow variables)" },
-    { flag: "--has-thoughts", description: "Show agent thinking process" },
-  ],
+    sessionId: {
+      type: "string",
+      valueHint: "<id>",
+      description: "Session ID for multi-turn conversation",
+    },
+    stream: { type: "switch", description: "Stream response (default: on in TTY)" },
+    pipelineIds: {
+      type: "string",
+      valueHint: "<ids>",
+      description: "Knowledge base pipeline IDs (comma-separated)",
+    },
+    memoryId: { type: "string", valueHint: "<id>", description: "Memory ID for long-term memory" },
+    bizParams: {
+      type: "string",
+      valueHint: "<json>",
+      description: "Business parameters JSON (workflow variables)",
+    },
+    hasThoughts: { type: "switch", description: "Show agent thinking process" },
+  },
   exampleArgs: [
     '--app-id abc123 --prompt "Hello"',
     '--app-id abc123 --prompt "Describe this image" --image https://example.com/photo.jpg',
@@ -41,12 +65,11 @@ export default defineCommand({
     '--app-id abc123 --prompt "Search for materials" --pipeline-ids pipe1,pipe2',
     '--app-id abc123 --prompt "Start" --biz-params \'{"key":"value"}\'',
   ],
-  async run(config: Config, flags: GlobalFlags) {
-    const appId = flags.appId as string;
-    const prompt = flags.prompt as string;
+  async run(config, flags) {
+    const appId = flags.appId;
+    const prompt = flags.prompt;
 
-    const shouldStream =
-      flags.stream === true || (flags.stream === undefined && process.stdout.isTTY);
+    const shouldStream = flags.stream || process.stdout.isTTY;
     const format = detectOutputFormat(config.output);
 
     const body: AppCompletionRequest = {
@@ -57,17 +80,17 @@ export default defineCommand({
     };
 
     if (flags.sessionId) {
-      body.input.session_id = flags.sessionId as string;
+      body.input.session_id = flags.sessionId;
     }
 
     // Pass image URLs via image_list
-    const imageUrls = flags.image as string[] | undefined;
+    const imageUrls = flags.image;
     if (imageUrls && imageUrls.length > 0) {
       body.input.image_list = imageUrls;
     }
 
     // Pass pre-uploaded file IDs
-    const fileIds = flags.fileId as string[] | undefined;
+    const fileIds = flags.fileId;
     if (fileIds && fileIds.length > 0) {
       body.input.file_ids = fileIds;
     }
@@ -77,20 +100,20 @@ export default defineCommand({
     }
 
     if (flags.pipelineIds) {
-      const ids = (flags.pipelineIds as string)
+      const ids = flags.pipelineIds
         .split(",")
         .map((s) => s.trim())
         .filter(Boolean);
       body.parameters!.rag_options = { pipeline_ids: ids };
     }
 
     if (flags.memoryId) {
-      body.parameters!.memory_id = flags.memoryId as string;
+      body.parameters!.memory_id = flags.memoryId;
     }
 
     if (flags.bizParams) {
       try {
-        body.input.biz_params = JSON.parse(flags.bizParams as string);
+        body.input.biz_params = JSON.parse(flags.bizParams);
       } catch {
         process.stderr.write("Error: --biz-params must be valid JSON\n");
         process.exit(1);

packages/commands/src/commands/app/list.ts

@@ -3,8 +3,6 @@ import {
   callConsoleGateway,
   resolveConsoleGatewayCredential,
   detectOutputFormat,
-  type Config,
-  type GlobalFlags,
 } from "bailian-cli-core";
 import { emitResult } from "bailian-cli-runtime";
 
@@ -14,37 +12,35 @@ export default defineCommand({
   description: "List Bailian applications",
   auth: "console",
   usageArgs: "[flags]",
-  options: [
-    {
-      flag: "--name <name>",
+  flags: {
+    name: {
+      type: "string",
+      valueHint: "<name>",
       description: "Filter by app name (keyword search)",
     },
-    {
-      flag: "--page <n>",
-      description: "Page number (default: 1)",
+    page: {
       type: "number",
+      valueHint: "<n>",
+      description: "Page number (default: 1)",
     },
-    {
-      flag: "--page-size <n>",
-      description: "Results per page (default: 30)",
+    pageSize: {
       type: "number",
+      valueHint: "<n>",
+      description: "Results per page (default: 30)",
     },
-    { flag: "--console-region <region>", description: "Console region" },
-    {
-      flag: "--console-site <site>",
+    consoleRegion: { type: "string", valueHint: "<region>", description: "Console region" },
+    consoleSite: {
+      type: "string",
+      valueHint: "<site>",
       description: "Console site: domestic, international",
     },
-    {
-      flag: "--console-switch-agent <uid>",
-      description: "Switch agent UID",
-      type: "number",
-    },
-  ],
+    consoleSwitchAgent: { type: "number", valueHint: "<uid>", description: "Switch agent UID" },
+  },
   exampleArgs: ["", "--name customer service", "--page 2 --page-size 10", "--output json"],
-  async run(config: Config, flags: GlobalFlags) {
-    const name = (flags.name as string) || "";
-    const pageNo = (flags.page as number) || 1;
-    const pageSize = (flags.pageSize as number) || 30;
+  async run(config, flags) {
+    const name = flags.name || "";
+    const pageNo = flags.page || 1;
+    const pageSize = flags.pageSize || 30;
     const format = detectOutputFormat(config.output);
 
     const credential = await resolveConsoleGatewayCredential(config);

packages/commands/src/commands/auth/login.ts

@@ -1,10 +1,4 @@
-import {
-  defineCommand,
-  readConfigFile,
-  writeConfigFile,
-  type Config,
-  type GlobalFlags,
-} from "bailian-cli-core";
+import { defineCommand, readConfigFile, writeConfigFile } from "bailian-cli-core";
 import { printQuickStart } from "bailian-cli-runtime";
 import { emitBare } from "bailian-cli-runtime";
 import {
@@ -17,21 +11,22 @@ export default defineCommand({
   description: "Authenticate with API key or console browser login (credentials can coexist)",
   auth: "none",
   usageArgs: "--api-key <key> | --console",
-  options: [
-    { flag: "--api-key <key>", description: "DashScope API key to store" },
-    {
-      flag: "--base-url <url>",
+  flags: {
+    apiKey: { type: "string", valueHint: "<key>", description: "DashScope API key to store" },
+    baseUrl: {
+      type: "string",
+      valueHint: "<url>",
       description: "DashScope API base URL (used with --api-key for validation)",
     },
-    {
-      flag: "--console",
+    console: {
+      type: "switch",
       description:
         "Sign in via browser; use --console-site to choose domestic (default) or international",
     },
-  ],
+  },
   exampleArgs: ["--api-key sk-xxxxx", "--console"],
   validate: (f) => (!f.console && !f.apiKey ? "Provide --api-key or --console" : undefined),
-  async run(config: Config, flags: GlobalFlags) {
+  async run(config, flags) {
     if (flags.console) {
       if (config.dryRun) {
         emitBare(
@@ -46,26 +41,23 @@ export default defineCommand({
       return;
     }
 
-    const envKey = process.env.DASHSCOPE_API_KEY;
-    if (envKey && !flags.apiKey) {
-      process.stderr.write(`Warning: DASHSCOPE_API_KEY is already set in environment.\n`);
-    }
-
-    const key = flags.apiKey as string;
+    // --api-key path; validate() guarantees apiKey on the non-console branch.
+    if (flags.apiKey) {
+      const key = flags.apiKey;
+      const baseUrl = flags.baseUrl || undefined;
+      const effectiveConfig = baseUrl ? { ...config, baseUrl } : config;
 
-    const baseUrl = (flags.baseUrl as string) || undefined;
-    const effectiveConfig = baseUrl ? { ...config, baseUrl } : config;
-
-    if (!config.dryRun) {
+      if (config.dryRun) {
+        emitBare("Would validate and save API key.");
+        return;
+      }
       if (baseUrl) {
         const existing = readConfigFile() as Record<string, unknown>;
         existing.base_url = baseUrl;
         await writeConfigFile(existing);
       }
       await validateAndPersistApiKey(effectiveConfig, key, effectiveConfig.baseUrl);
       printQuickStart();
-    } else {
-      emitBare("Would validate and save API key.");
     }
   },
 });

packages/commands/src/commands/auth/logout.ts

@@ -4,8 +4,6 @@ import {
   readConfigFile,
   writeConfigFile,
   getConfigPath,
-  type Config,
-  type GlobalFlags,
 } from "bailian-cli-core";
 import { emitBare } from "bailian-cli-runtime";
 
@@ -21,16 +19,15 @@ export default defineCommand({
   description: "Clear stored credentials",
   auth: "none",
   usageArgs: "[--console] [--yes] [--dry-run]",
-  options: [
-    {
-      flag: "--console",
+  flags: {
+    console: {
+      type: "switch",
       description: "Only clear the console access_token, keep api_key intact",
-      type: "boolean",
     },
-    { flag: "--yes", description: "Skip confirmation prompt" },
-  ],
+    yes: { type: "switch", description: "Skip confirmation prompt" },
+  },
   exampleArgs: ["", "--console", "--dry-run", "--yes"],
-  async run(config: Config, flags: GlobalFlags) {
+  async run(config, flags) {
     const file = readConfigFile();
 
     if (flags.console) {