gaoding-cli 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/src/middleware/error-handler.js

@@ -1,21 +1,21 @@
 import { ApiError } from "../api/hub-client.js";
 import { DirectApiError } from "../api/direct-client.js";
-import { failedEnvelope, emitJson } from "../core/output/envelope.js";
+import { failedEnvelope, emitJson, publicCliErrorBody, } from "../core/output/envelope.js";
 import { CliUsageError } from "../core/output/cli-error.js";
 import { isVerbose, isDebug } from "../utils/config.js";
 import { isTransientNetworkError } from "../utils/transient-network-error.js";
 import { detectEntitlementIssue, entitlementCliError, ENTITLEMENT_PRICING_URL, resolveEntitlementPricingUrl, } from "../utils/entitlement.js";
 import { redactSensitiveText, redactSensitiveValue } from "../utils/redact.js";
+const jsonFailureProjectors = new WeakMap();
 const ERROR_GUIDES = {
     AUTH_MISSING: "请先登录：\n    gd-cli auth login",
     AUTH_EXPIRED: "凭证已过期，请重新登录：\n    gd-cli auth login",
     AUTH_REFRESH_FAILED: "凭证刷新失败：\n    gd-cli auth login",
     AUTH_SCOPE_DENIED: "权限不足，请重新授权",
-    ORG_BIND_EXPIRED: "组织绑定已过期：\n    gd-cli org switch",
     ORG_INVALID: "当前组织无效：\n    gd-cli org list",
     PARAM_MISSING: "查看命令帮助：\n    gd-cli <command> --help",
     PARAM_INVALID: "参数值不合法，请检查参数格式",
-    TOOL_NOT_FOUND: "工具不存在：\n    gd-cli tools list",
+    TOOL_NOT_FOUND: "能力路由不存在，请检查输入或重试当前命令",
     APP_NOT_FOUND: "Workflow 不存在：\n    gd-cli workflows list",
     TASK_NOT_FOUND: "任务不存在或已过期",
     RATE_LIMITED: "请求过于频繁，请稍后重试",
@@ -29,7 +29,7 @@ export function withErrorHandler(handler) {
         }
         catch (error) {
             if (shouldEmitJsonError(args)) {
-                emitJson(failedEnvelope(redactSensitiveValue(toCliErrorBody(error))));
+                emitJsonFailure(commandFromArgs(args), error);
                 process.exit(1);
             }
             if (error instanceof CliUsageError) {
@@ -81,22 +81,26 @@ export function withErrorHandler(handler) {
         }
     };
 }
-function shouldEmitJsonError(args) {
-    let current = args.find(isCommandLike);
-    while (current) {
-        if (!isCommandLike(current))
-            return false;
-        const format = current.opts().format;
-        const json = current.opts().json;
-        if (json === true)
-            return true;
-        if (format === "json")
-            return true;
-        if (format)
-            return false;
-        current = current.parent;
-    }
-    return !process.stdout.isTTY;
+export function shouldEmitJsonError(args) {
+    const command = commandFromArgs(args);
+    return command?.opts().json === true;
+}
+export function setJsonFailureProjector(command, projector) {
+    jsonFailureProjectors.set(command, projector);
+}
+export function jsonFailureEnvelopeFor(command, error) {
+    const body = redactSensitiveValue(toCliErrorBody(error));
+    const projector = command ? jsonFailureProjectors.get(command) : undefined;
+    if (projector)
+        return projector(body);
+    const commandName = command ? publicCommandName(command) : "";
+    return failedEnvelope(body, commandName ? { command: commandName } : undefined);
+}
+export function emitJsonFailure(command, error) {
+    emitJson(jsonFailureEnvelopeFor(command, error));
+}
+function commandFromArgs(args) {
+    return [...args].reverse().find(isCommandLike);
 }
 function isCommandLike(value) {
     return (!!value &&
@@ -104,7 +108,10 @@ function isCommandLike(value) {
         "opts" in value &&
         typeof value.opts === "function");
 }
-function toCliErrorBody(error) {
+export function toCliErrorBody(error) {
+    return publicCliErrorBody(toCliErrorBodyInternal(error));
+}
+function toCliErrorBodyInternal(error) {
     if (error instanceof CliUsageError) {
         return error.body;
     }
@@ -128,38 +135,40 @@ function toCliErrorBody(error) {
         });
         if (entitlement)
             return redactSensitiveValue(entitlementCliError(entitlement, error.body));
-        if (isToolRouteUnavailableMessage(parsed.message ?? error.message)) {
-            return toolRouteUnavailableCliError(parsed.message ?? error.message, redactSensitiveValue(error.body));
+        if (parsed.message && isToolRouteUnavailableMessage(parsed.message)) {
+            return toolRouteUnavailableCliError(parsed.message, redactSensitiveValue(error.body));
         }
         return {
             code: parsed.code ?? `HTTP_${error.statusCode}`,
             type: error.statusCode === 401 ? "auth" : "business",
             message: parsed.message
                 ? normalizeBusinessMessage(parsed.message)
-                : redactSensitiveText(error.message),
+                : publicApiFailureMessage(error.statusCode),
             hint: redactSensitiveText(parsed.hint ?? directApiHint(parsed, error.url) ?? ""),
             retryable: false,
             detail: redactSensitiveValue(error.body),
         };
     }
     if (error instanceof ApiError) {
-        const parsed = parseJsonObject(error.body);
-        const code = stringField(parsed, "error_code") ?? stringField(parsed, "error") ?? "API_ERROR";
-        const message = stringField(parsed, "message") ?? error.message;
+        const parsedBody = parseJsonObject(error.body);
+        const parsed = parseDirectApiErrorBody(parsedBody ?? error.body);
+        const code = parsed.code ?? "API_ERROR";
+        const message = parsed.message ?? publicApiFailureMessage(error.statusCode);
         const entitlement = detectEntitlementIssue({
             code,
             message,
-            detail: parsed ?? error.body,
+            detail: parsedBody ?? error.body,
         });
-        if (entitlement)
-            return redactSensitiveValue(entitlementCliError(entitlement, parsed ?? error.body));
+        if (entitlement) {
+            return redactSensitiveValue(entitlementCliError(entitlement, parsedBody ?? error.body));
+        }
         return {
             code,
             type: code.startsWith("AUTH") ? "auth" : "business",
             message: redactSensitiveText(message),
-            hint: redactSensitiveText(stringField(parsed, "suggestion") ?? errorGuide(code) ?? ""),
+            hint: redactSensitiveText(parsed.hint ?? errorGuide(code) ?? ""),
             retryable: false,
-            detail: redactSensitiveValue(parsed ?? error.body),
+            detail: redactSensitiveValue(parsedBody ?? error.body),
         };
     }
     if (error instanceof Error) {
@@ -210,32 +219,10 @@ function printCliUsageError(body) {
     console.error(`\n  错误码: ${body.code}`);
     if (body.reason)
         console.error(`  原因: ${body.reason}`);
-    const detail = body.detail && typeof body.detail === "object" && !Array.isArray(body.detail)
-        ? body.detail
-        : undefined;
-    const appId = body.app_id ?? stringField(detail, "app_id");
-    const toolId = body.tool_id ?? stringField(detail, "tool_id");
-    if (appId)
-        console.error(`  Workflow: ${appId}`);
-    if (toolId)
-        console.error(`  Tool: ${toolId}`);
-    const missingTools = Array.isArray(body.missing_tools)
-        ? body.missing_tools
-            .map((item) => typeof item === "string"
-            ? item
-            : stringField(item, "id") ?? "")
-            .filter(Boolean)
-        : [];
-    if (missingTools.length > 0) {
-        console.error(`  缺失 Tool: ${missingTools.join(", ")}`);
-    }
     if (body.hint)
         console.error(`\n  说明: ${body.hint}`);
     if (body.next_command)
         console.error(`\n  下一步: ${body.next_command}`);
-    const listCommand = stringField(detail, "list_command");
-    if (listCommand)
-        console.error(`  查看状态: ${listCommand}`);
     console.error("");
 }
 function parseDirectApiErrorBody(body) {
@@ -250,12 +237,29 @@ function parseDirectApiErrorBody(body) {
         code: stringField(nestedError, "error_code") ??
             stringField(nestedError, "code") ??
             stringField(value, "error_code") ??
-            stringField(value, "code"),
+            stringField(value, "code") ??
+            stringField(value, "error"),
         errorName: stringField(nestedError, "error_name") ??
             stringField(value, "error_name"),
         message: stringField(nestedError, "message") ?? stringField(value, "message"),
+        hint: stringField(nestedError, "suggestion") ??
+            stringField(nestedError, "hint") ??
+            stringField(value, "suggestion") ??
+            stringField(value, "hint"),
     };
 }
+function publicApiFailureMessage(statusCode) {
+    return `业务请求失败（HTTP ${statusCode}）`;
+}
+function publicCommandName(command) {
+    const names = [];
+    let current = command;
+    while (current.parent) {
+        names.unshift(current.name());
+        current = current.parent;
+    }
+    return names.join(" ");
+}
 function parseJsonObject(value) {
     try {
         const parsed = JSON.parse(value);
@@ -367,7 +371,7 @@ function toolRouteUnavailableCliError(message, detail) {
         type: "business",
         message: normalizeToolRouteUnavailableMessage(message),
         reason: "tool-route-unavailable",
-        hint: "当前 Tool 的平台生成路由不可用。Agent 应停止重试，不要切换模型、环境、团队或调用内部 raw.dify；请保留本次输入并联系平台确认能力配置。",
+        hint: "当前能力的生成路由不可用。请停止重试，不要切换模型、环境或团队；请保留本次输入并联系平台确认能力配置。",
         retryable: false,
         detail,
     };
@@ -386,7 +390,7 @@ function isToolRouteUnavailableMessage(message) {
 function normalizeToolRouteUnavailableMessage(message) {
     const normalized = normalizeBusinessMessage(message);
     if (/没有可用的工具|tool-intent 没有返回|tool intent 没有返回/i.test(normalized)) {
-        return "当前 Tool 的平台生成路由不可用，未发起生成任务。";
+        return "当前能力的生成路由不可用，未发起生成任务。";
     }
     return normalized;
 }

package/dist/src/program.d.ts

@@ -1,2 +1,3 @@
 import { Command } from "commander";
 export declare function createProgram(): Promise<Command>;
+export declare function parseProgram(program: Command, argv?: readonly string[]): Promise<void>;

package/dist/src/program.js

@@ -1,152 +1,167 @@
-import { Command, Option } from "commander";
+import { Command, CommanderError } from "commander";
 import { CLI_VERSION } from "./utils/config.js";
 import { registerAuthCommand } from "./commands/auth.js";
 import { registerOrgCommand } from "./commands/org.js";
 import { registerWorkflowsCommand } from "./commands/workflows.js";
-import { registerToolsCommand } from "./commands/tools.js";
+import { registerCreativeCommand } from "./commands/creative.js";
 import { registerDamCommand } from "./commands/dam.js";
-import { registerModelsCommand } from "./commands/models.js";
 import { registerUpdateCommand } from "./commands/update.js";
 import { registerSkillsCommand } from "./commands/skills.js";
-import { registerUsageCommand } from "./commands/usage.js";
 import { maybeNotifyUpdate } from "./update/notifier.js";
-import { formatOutput } from "./middleware/output.js";
-import { buildManifest, buildTopExamples, rowsForManifest, } from "./registry/agent-contracts.js";
-import { resolveListOutputFormat } from "./utils/list-output-format.js";
-import { setStaticHelp } from "./utils/static-help.js";
+import { installAuthPreflight } from "./middleware/auth.js";
+import { CliUsageError } from "./core/output/cli-error.js";
+import { emitJsonFailure } from "./middleware/error-handler.js";
 export async function createProgram() {
     const program = new Command();
     program
         .name("gd-cli")
         .usage("<command> [options]")
         .description("GD CLI — 让稿定成为 Agent 的创意生产引擎")
-        .version(CLI_VERSION)
-        .addOption(new Option("-f, --format <format>", "输出格式: human / table / json / text").choices(["json", "human", "table", "text"]))
-        .addOption(new Option("--json", "等同于 --format json，推荐 Agent 和脚本使用"))
-        .addOption(new Option("--no-input", "禁止交互，适合 CI / Agent"))
-        .addOption(new Option("--yes", "跳过确认"))
-        .addOption(new Option("--verbose", "输出详细日志").hideHelp().default(false));
-    setStaticHelp(program, TOP_LEVEL_HELP);
-    program
-        .command("manifest")
-        .description("输出 Agent 可解析的 gd-cli 能力清单")
-        .action((_opts, command) => {
-        const manifest = buildManifest("all");
-        const format = resolveListOutputFormat(command);
-        formatOutput(format === "json" ? manifest : rowsForManifest(manifest), format);
-    });
-    program
-        .command("examples")
-        .description("查看常用场景示例")
-        .action((_opts, command) => {
-        const examples = buildTopExamples();
-        const format = resolveExplicitExamplesFormat(command);
-        if (format === "json") {
-            formatOutput(examples, "json");
-        }
-        else {
-            printExamples(examples);
-        }
-    });
-    const agent = program
-        .command("agent", { hidden: true })
-        .description("Agent 调用 gd-cli 的机器可读入口说明")
-        .action(() => {
-        console.log(AGENT_HELP.trim());
-    });
-    agent.addHelpText("afterAll", `\n${AGENT_HELP}`);
+        .version(CLI_VERSION);
     registerAuthCommand(program);
     registerOrgCommand(program);
+    registerCreativeCommand(program);
     registerWorkflowsCommand(program);
-    registerToolsCommand(program);
     registerSkillsCommand(program);
-    registerModelsCommand(program);
     registerDamCommand(program);
     registerUpdateCommand(program);
-    registerUsageCommand(program);
+    installAuthPreflight(program);
     program.hook("postAction", async (_thisCommand, actionCommand) => {
         await maybeNotifyUpdate(actionCommand);
     });
     return program;
 }
-const TOP_LEVEL_HELP = `
-Usage: gd-cli <command> [options]
-
-GD CLI — 让稿定成为 Agent 的创意生产引擎
-
-核心命令:
-  auth      登录、退出、查看登录状态
-  org       查看和切换当前组织
-  workflows 运行完整创意场景任务，例如商品上新、批量海报、内容矩阵
-  tools     调用单项 AI 创意能力，例如生图、抠图、高清化、标题生成
-  skills    安装和管理 gd-cli Agent Skill
-  dam       素材管理，上传、查询、删除素材
-  update    检查并升级 gd-cli
-
-常用流程:
-  gd-cli auth login                         登录稿定账号
-  gd-cli org list                           查看可用组织
-  gd-cli org switch                         切换当前组织
-  gd-cli workflows list                     查看完整创意场景
-  gd-cli tools list                         查看单项 AI 创意能力
-  gd-cli dam upload ./image.png             上传素材到 DAM
-
-常用选项:
-  -V, --version          output the version number
-  -f, --format <format>  输出格式: human / table / json / text
-  --json                 等同于 --format json，推荐 Agent 和脚本使用
-  --no-input             禁止交互，适合 CI / Agent
-  --yes                  跳过确认
-  -h, --help             display help for command
-
-更多:
-  gd-cli examples        查看常用场景示例
-  gd-cli manifest        可解析的能力清单
-`;
-const AGENT_HELP = `
-Agent 推荐入口:
-  gd-cli manifest --format json             读取完整能力清单
-  gd-cli workflows manifest --format json   读取 Workflows 清单
-  gd-cli tools manifest --format json       读取 Tools 清单
-  gd-cli workflows schema <workflow-id> --format json 查看 Workflow 输入/输出结构
-  gd-cli tools schema <tool-id> --format json 查看 Tool 输入/输出结构
-
-调用规则:
-  1. 优先用 --format json 或 --json。
-  2. 复杂输入用 --input <json-file> 或 stdin: cat input.json | gd-cli tools call <tool-id> - --json。
-  3. 完整业务场景优先选 workflows；单项能力选 tools；素材复用选 dam。
-  4. Agent 不切换模型、环境或组织；这些由 CLI 配置和用户显式命令管理。
-`;
-function resolveExplicitExamplesFormat(command) {
-    const root = command.parent;
-    const opts = (root?.opts() ?? {});
-    if (opts.json)
-        return "json";
-    const source = root?.getOptionValueSource("format");
-    return source && source !== "default" && source !== "implied"
-        ? opts.format ?? "human"
-        : "human";
-}
-function printExamples(payload) {
-    const examples = Array.isArray(payload.examples) ? payload.examples : [];
-    console.log("常用场景示例\n");
-    examples.forEach((item, index) => {
-        const record = item;
-        console.log(`${index + 1}. ${String(record.title ?? "")}`);
-        const description = record.description;
-        if (typeof description === "string" && description.trim()) {
-            console.log(`   ${description.trim()}`);
+export async function parseProgram(program, argv = process.argv) {
+    const userArgs = argv.slice(2);
+    const jsonLeaf = resolveExplicitJsonLeaf(program, userArgs);
+    const capturedErrors = [];
+    const configuredCommands = allCommands(program).map((command) => {
+        const output = command.configureOutput();
+        const writeErr = output.writeErr ?? ((text) => process.stderr.write(text));
+        command.configureOutput({
+            writeErr: (text) => capturedErrors.push({ text, write: writeErr }),
+        });
+        command.exitOverride();
+        return { command, writeErr };
+    });
+    let actionStarted = false;
+    program.hook("preAction", () => {
+        actionStarted = true;
+    });
+    try {
+        await program.parseAsync([...argv]);
+    }
+    catch (error) {
+        if (error instanceof CommanderError && error.exitCode === 0)
+            return;
+        if (!actionStarted && jsonLeaf) {
+            emitJsonFailure(jsonLeaf, parseFailure(error, jsonLeaf));
+            process.exitCode = error instanceof CommanderError
+                ? Math.max(1, error.exitCode)
+                : 1;
+            return;
+        }
+        for (const captured of capturedErrors)
+            captured.write(captured.text);
+        if (error instanceof CommanderError) {
+            process.exitCode = error.exitCode;
+            return;
+        }
+        throw error;
+    }
+    finally {
+        for (const { command, writeErr } of configuredCommands) {
+            command.configureOutput({ writeErr });
         }
-        console.log("");
-        console.log(`   ${String(record.command ?? "")}`);
-        const input = record.input_json;
-        if (input && typeof input === "object" && Object.keys(input).length > 0) {
-            console.log("");
-            console.log("   input_json:");
-            for (const [key, value] of Object.entries(input)) {
-                console.log(`     ${key}: ${String(value)}`);
+    }
+}
+function resolveExplicitJsonLeaf(program, args) {
+    let current = program;
+    let index = 0;
+    let commandIndex = -1;
+    while (current.commands.length > 0) {
+        let nextCommand;
+        while (index < args.length) {
+            const token = args[index];
+            if (token === "--")
+                return undefined;
+            if (token.startsWith("-")) {
+                index += optionWidth(current, args, index);
+                continue;
             }
+            nextCommand = current.commands.find((candidate) => candidate.name() === token || candidate.aliases().includes(token));
+            if (!nextCommand)
+                return undefined;
+            commandIndex = index;
+            index += 1;
+            break;
         }
-        console.log("");
+        if (!nextCommand)
+            return undefined;
+        current = nextCommand;
+    }
+    if (commandIndex < 0 ||
+        !current.options.some((option) => option.long === "--json")) {
+        return undefined;
+    }
+    return hasExplicitJsonOption(current, args.slice(commandIndex + 1))
+        ? current
+        : undefined;
+}
+function hasExplicitJsonOption(command, args) {
+    for (let index = 0; index < args.length;) {
+        const token = args[index];
+        if (token === "--")
+            return false;
+        if (token === "--json")
+            return true;
+        index += optionWidth(command, args, index);
+    }
+    return false;
+}
+function optionWidth(command, args, index) {
+    const token = args[index];
+    const flag = token.includes("=") ? token.slice(0, token.indexOf("=")) : token;
+    const option = command.options.find((candidate) => candidate.long === flag || candidate.short === flag);
+    if (!option || token.includes("="))
+        return 1;
+    if (option.required)
+        return index + 1 < args.length ? 2 : 1;
+    if (option.optional &&
+        index + 1 < args.length &&
+        !args[index + 1].startsWith("-")) {
+        return 2;
+    }
+    return 1;
+}
+function parseFailure(error, command) {
+    const missingCodes = new Set([
+        "commander.missingArgument",
+        "commander.optionMissingArgument",
+        "commander.missingMandatoryOptionValue",
+    ]);
+    const code = error instanceof CommanderError && missingCodes.has(error.code)
+        ? "PARAM_MISSING"
+        : "PARAM_INVALID";
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    const message = rawMessage.replace(/^error:\s*/i, "").trim() || "参数不合法";
+    return new CliUsageError({
+        code,
+        type: "validation",
+        message,
+        hint: `运行 gd-cli ${publicCommandName(command)} --help 查看参数说明。`,
+        retryable: false,
     });
 }
+function publicCommandName(command) {
+    const names = [];
+    let current = command;
+    while (current.parent) {
+        names.unshift(current.name());
+        current = current.parent;
+    }
+    return names.join(" ");
+}
+function allCommands(root) {
+    return [root, ...root.commands.flatMap(allCommands)];
+}

package/dist/src/registry/agent-contracts.d.ts

@@ -1,43 +1,23 @@
-import type { OutputSpec, ParamSpec } from "./types.js";
-import { type CapabilityPolicy, type CapabilitySource, type CapabilityStatus } from "../utils/capability-metadata.js";
-type CapabilityKind = "workflow" | "tool";
-type ManifestScope = "all" | "workflows" | "tools";
+import type { ParamSpec } from "./types.js";
+export declare const PUBLIC_WORKFLOW_MEDIA_PATTERN = "^kv_\\d+_\\d+$";
+export interface PublicWorkflowOutputDefinition {
+    textFields: readonly string[];
+    mediaFields: readonly string[];
+    overlayFields: readonly string[];
+    ratioFields: readonly string[];
+    ratios: "record" | "array";
+    sellingPoints?: boolean;
+    mediaPattern?: string;
+}
 export interface JsonSchemaObject {
     type: "object";
     properties: Record<string, Record<string, unknown>>;
     required: string[];
     additionalProperties?: boolean;
-}
-export interface CapabilityManifestCommand {
-    id: string;
-    type: CapabilityKind | "dam" | "org";
-    category: string;
-    title: string;
-    description: string;
-    canonical_command: string;
-    input_schema_command?: string;
-    examples_command?: string;
-    output: "json";
-    safe_for_agent: boolean;
-    source: CapabilitySource;
-    status: CapabilityStatus;
-    policy: CapabilityPolicy;
-    dependency_tools?: string[];
-    affected_workflows?: string[];
-}
-export interface CapabilityManifest {
-    name: "gd-cli";
-    version: string;
-    description: string;
-    commands: CapabilityManifestCommand[];
+    patternProperties?: Record<string, Record<string, unknown>>;
 }
 export declare function buildInputJsonSchema(params: ParamSpec[], extraProperties?: Record<string, Record<string, unknown>>): JsonSchemaObject;
-export declare function buildOutputJsonSchema(output: OutputSpec): JsonSchemaObject;
-export declare function buildToolSchema(toolId: string): Record<string, unknown>;
+export declare function resolvePublicWorkflowOutputDefinition(appId: string): PublicWorkflowOutputDefinition;
+export declare function buildOutputJsonSchema(appId: string): JsonSchemaObject;
 export declare function buildWorkflowSchema(appId: string): Record<string, unknown>;
-export declare function buildToolExamples(toolId: string): Record<string, unknown>;
 export declare function buildWorkflowExamples(appId: string): Record<string, unknown>;
-export declare function buildManifest(scope?: ManifestScope): CapabilityManifest;
-export declare function rowsForManifest(manifest: CapabilityManifest): Record<string, string>[];
-export declare function buildTopExamples(): Record<string, unknown>;
-export {};