gaoding-cli 1.0.0-alpha.5

package/dist/src/commands/tools.js

@@ -0,0 +1,383 @@
+import { Option } from "commander";
+import { ToolInvoker } from "../api/tool-invoker.js";
+import { withAuth } from "../middleware/auth.js";
+import { withErrorHandler } from "../middleware/error-handler.js";
+import { formatOutput, rowsForToolList } from "../middleware/output.js";
+import { resolveInvokeOutputFormat, resolveListOutputFormat, } from "../utils/list-output-format.js";
+import { createSpinner } from "../utils/spinner.js";
+import { resolveToolActivityLabel, toolActivityLabel, } from "../utils/tool-display.js";
+import { enrichUploadParamsIfNeeded } from "../utils/enrich-upload-params.js";
+import { appendToolQuickExample } from "../utils/help-verify.js";
+import { emitJson, wrapEnvelope, shouldEmitEnvelope } from "../core/output/envelope.js";
+import { PUBLIC_DIRECT_TOOLS, resolvePublicToolSpec, } from "../registry/direct-registry.js";
+import { buildManifest, buildToolExamples, buildToolSchema, rowsForManifest, } from "../registry/agent-contracts.js";
+import { applySetEntries, collectArg, readJsonInput } from "../utils/input-json.js";
+import { setStaticHelp } from "../utils/static-help.js";
+import { printCapabilityExamples, printCapabilitySchema, } from "../utils/capability-presenter.js";
+import { capabilityMetadata } from "../utils/capability-metadata.js";
+export function registerToolsCommand(program) {
+    const tools = program
+        .command("tools")
+        .usage("<command> [options]")
+        .description("单项 AI 创意能力 Tools")
+        .configureHelp({ showGlobalOptions: true });
+    setStaticHelp(tools, TOOLS_HELP);
+    tools
+        .command("list")
+        .alias("ls")
+        .description("列出内置 Tools")
+        .option("--category <cat>", "分类: image / text / video / infrastructure")
+        .action(withErrorHandler(async (options, command) => {
+        const opts = options;
+        const cmd = command;
+        let items = PUBLIC_DIRECT_TOOLS;
+        if (opts.category) {
+            const cat = String(opts.category);
+            items = items.filter((item) => item.category === cat);
+        }
+        const publicItems = items.map(toPublicToolPayload);
+        const format = resolveListOutputFormat(cmd);
+        if (shouldEmitEnvelope(format)) {
+            emitJson(wrapEnvelope({ tools: publicItems }, { command: "tools ls" }));
+        }
+        else if (format === "json") {
+            formatOutput(publicItems, format);
+        }
+        else {
+            formatOutput(rowsForToolList(publicItems), format);
+        }
+    }));
+    tools
+        .command("info <tool-id>")
+        .description("查看工具详情")
+        .action(withErrorHandler(async (toolId, _opts, command) => {
+        const cmd = command;
+        const detail = resolvePublicToolSpec(String(toolId));
+        if (!detail)
+            throw new Error(`未找到工具: ${String(toolId)}`);
+        const payload = toPublicToolPayload(detail);
+        const format = cmd.parent?.parent?.opts().format ?? "json";
+        if (shouldEmitEnvelope(format)) {
+            emitJson(wrapEnvelope(payload, { command: "tools info", tool_id: toolId }));
+        }
+        else {
+            formatOutput(payload, format);
+        }
+    }));
+    tools
+        .command("schema <tool-id>")
+        .description("查看输入/输出 JSON Schema")
+        .action(withErrorHandler(async (toolId, _opts, command) => {
+        const cmd = command;
+        const payload = buildToolSchema(String(toolId));
+        const format = resolveListOutputFormat(cmd);
+        if (format === "json") {
+            formatOutput(payload, "json");
+        }
+        else {
+            printCapabilitySchema(payload);
+        }
+    }));
+    tools
+        .command("examples <tool-id>")
+        .description("查看调用示例")
+        .action(withErrorHandler(async (toolId, _opts, command) => {
+        const cmd = command;
+        const payload = buildToolExamples(String(toolId));
+        const format = resolveListOutputFormat(cmd);
+        if (format === "json") {
+            formatOutput(payload, "json");
+        }
+        else {
+            printCapabilityExamples(payload);
+        }
+    }));
+    tools
+        .command("manifest")
+        .description("输出 Tools 机器可读能力清单")
+        .action((_opts, command) => {
+        const manifest = buildManifest("tools");
+        const format = resolveListOutputFormat(command);
+        formatOutput(format === "json" ? manifest : rowsForManifest(manifest), format);
+    });
+    const callCmd = tools
+        .command("call <tool-id> [input]")
+        .usage("<tool-id> [input] [options]")
+        .description("调用指定工具")
+        .option("--input <file>", "从 JSON 文件读取输入，使用 - 表示 stdin")
+        .option("--set <key=value>", "直接传入单个字段，可重复", collectArg)
+        .option("--asset <id-or-url>", "传入 DAM asset_id 或 CDN URL，可重复", collectArg)
+        .option("--prompt <text>", "文字提示词")
+        .option("--brief <text>", "业务 brief / 商品描述")
+        .option("--image <url>", "输入图片 URL")
+        .option("--image-url <url>", "输入图片 URL")
+        .option("--image-file <path>", "输入图片本地路径")
+        .option("--image-prompt <text>", "图片内容描述，不上传本地图片")
+        .option("--require-image", "要求必须提供真实参考图；缺图时不退化为文生", false)
+        .option("--video <url>", "输入视频 URL 或本地路径")
+        .option("--video-url <url>", "输入视频 URL")
+        .option("--video-file <path>", "输入视频本地路径")
+        .option("--style <code>", "风格代码")
+        .option("--style-code <code>", "风格/模型代码")
+        .option("--model <code-or-name>", "模型 code / 名称 / auto")
+        .option("--ratio <ratio>", "宽高比")
+        .option("--resolution <value>", "分辨率参数")
+        .option("--duration <value>", "视频时长参数")
+        .option("--content-id <id>", "指定后端 content_id；部分工具未传或非法时会自动生成")
+        .option("--mask <url>", "蒙版图 URL")
+        .option("--mask-url <url>", "蒙版图 URL")
+        .option("--mask-file <path>", "蒙版图本地路径")
+        .option("--compose-mask", "将后端 mask 与原图合成透明 PNG（默认开启）")
+        .option("--raw-mask", "仅返回后端 mask，不做合成", false)
+        .option("--width <n>", "目标宽度", parseInt)
+        .option("--height <n>", "目标高度", parseInt)
+        .option("--mode <mode>", "模式参数")
+        .option("--file <path>", "本地文件路径")
+        .option("--allow-sensitive-path", "确认上传默认受保护的本地路径", false)
+        .addOption(new Option("--arg <entry>", "内部调试参数 key=value，可重复").hideHelp().argParser(collectArg))
+        .option("--async", "异步模式", false)
+        .option("--timeout <seconds>", "超时秒数；未传时使用工具默认值")
+        .allowUnknownOption(true);
+    callCmd.action(withErrorHandler(async (toolName, input, options, command) => {
+        await withAuth(async () => {
+            await runToolCall(toolName, input, options, command);
+        })(toolName, input, options, command);
+    }));
+    loadDynamicToolAliases(tools);
+    callCmd.addHelpText("afterAll", TOOL_CALL_HELP);
+}
+export async function runToolCall(toolName, input, opts, cmd) {
+    const spec = resolvePublicToolSpec(toolName);
+    if (!spec) {
+        throw new Error(`未找到工具: ${toolName}。临时生成 CDN URL 可使用 gd-cli tools call upload --file <file>；DAM 入库请使用 gd-cli dam upload <file>`);
+    }
+    const inputOption = optionalString(opts.input);
+    const inputOptionIsJson = inputOption ? shouldReadJsonInput(inputOption) : false;
+    const inputArgIsJson = input ? shouldReadJsonInput(input) : false;
+    let params = {};
+    if (inputArgIsJson && input) {
+        params = { ...params, ...(await readJsonInput(input)) };
+    }
+    if (inputOptionIsJson && inputOption) {
+        params = { ...params, ...(await readJsonInput(inputOption)) };
+    }
+    if (input && !inputArgIsJson)
+        params.input = input;
+    if (inputOption && !inputOptionIsJson)
+        params.input = inputOption;
+    params = mergeToolCallOptions(params, opts);
+    applySetEntries(params, opts.set);
+    applyAssetEntries(params, opts.asset);
+    const canonicalToolName = spec?.name ?? toolName;
+    const merged = enrichUploadParamsIfNeeded(canonicalToolName, params);
+    const label = await resolveToolActivityLabel(canonicalToolName);
+    const spinner = createSpinner(`${label} · 处理中…`);
+    if (process.stderr.isTTY)
+        spinner.start();
+    const invoker = new ToolInvoker();
+    const result = await invoker.invoke(canonicalToolName, merged, {
+        async: !!opts.async,
+        timeout: resolveTimeoutSeconds(opts.timeout, spec.timeout),
+    });
+    if (process.stderr.isTTY) {
+        if (result.status === "completed")
+            spinner.succeed(`${label} · 已完成`);
+        else if (result.status === "failed")
+            spinner.fail(`${label} · 失败`);
+        else
+            spinner.stop();
+    }
+    const format = resolveInvokeOutputFormat(cmd);
+    if (shouldEmitEnvelope(format)) {
+        emitJson(wrapEnvelope(result, { command: "tools call", tool_id: canonicalToolName }));
+    }
+    else {
+        formatOutput(result, format, { activityLabel: label });
+    }
+}
+export function mergeToolCallOptions(base, opts) {
+    const params = { ...base };
+    const ignoredKeys = new Set(["async", "timeout", "input", "set", "asset"]);
+    const normalizedKeys = {
+        imageUrl: "image_url",
+        "image-url": "image_url",
+        imageFile: "image_file",
+        "image-file": "image_file",
+        imagePrompt: "image_prompt",
+        "image-prompt": "image_prompt",
+        maskUrl: "mask_url",
+        "mask-url": "mask_url",
+        maskFile: "mask_file",
+        "mask-file": "mask_file",
+        style: "style_code",
+        styleCode: "style_code",
+        requireImage: "require_image",
+        "require-image": "require_image",
+        videoUrl: "video_url",
+        "video-url": "video_url",
+        videoFile: "video_file",
+        "video-file": "video_file",
+        contentId: "content_id",
+        "content-id": "content_id",
+        allowSensitivePath: "allow_sensitive_path",
+        "allow-sensitive-path": "allow_sensitive_path",
+        composeMask: "compose_mask",
+        "compose-mask": "compose_mask",
+        rawMask: "raw_mask",
+        "raw-mask": "raw_mask",
+    };
+    for (const [key, value] of Object.entries(opts)) {
+        if (ignoredKeys.has(key) || value === undefined || value === false)
+            continue;
+        params[normalizedKeys[key] ?? key] = value;
+    }
+    return params;
+}
+function shouldReadJsonInput(value) {
+    return value === "-" || /\.json$/i.test(value);
+}
+function optionalString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
+function applyAssetEntries(target, entries) {
+    if (!Array.isArray(entries) || entries.length === 0)
+        return;
+    const assets = entries.map(String).filter(Boolean);
+    if (assets.length === 0)
+        return;
+    target.assets = assets;
+    if (!target.image && assets.length === 1)
+        target.image = assets[0];
+    if (!target.images && assets.length > 1)
+        target.images = assets;
+}
+function resolveTimeoutSeconds(value, fallback) {
+    if (value === undefined || value === null || value === "")
+        return fallback;
+    const parsed = Number.parseInt(String(value), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return fallback;
+    return parsed;
+}
+async function loadDynamicToolAliases(toolsCmd) {
+    const seen = new Set();
+    const reserved = new Set([
+        "list",
+        "ls",
+        "search",
+        "info",
+        "schema",
+        "examples",
+        "manifest",
+        "call",
+        "install",
+        "uninstall",
+    ]);
+    for (const spec of PUBLIC_DIRECT_TOOLS) {
+        for (const commandName of [spec.name, ...(spec.aliases ?? [])]) {
+            if (seen.has(commandName) || reserved.has(commandName)) {
+                continue;
+            }
+            seen.add(commandName);
+            registerDynamicToolAlias(toolsCmd, spec, commandName);
+        }
+    }
+}
+function registerDynamicToolAlias(parent, spec, commandName = spec.name) {
+    const cmd = parent
+        .command(commandName, { hidden: true })
+        .description(spec.description)
+        .configureHelp({ showGlobalOptions: true });
+    for (const param of spec.input ?? []) {
+        const flag = param.cli_flag ?? `--${param.name}`;
+        const desc = param.description + (param.required ? " (必填)" : "");
+        if (param.type === "boolean") {
+            cmd.option(flag, desc, param.default);
+        }
+        else {
+            cmd.option(`${flag} <value>`, desc, param.default);
+        }
+    }
+    cmd.action(withErrorHandler(async (...args) => {
+        await withAuth(async (options, command) => {
+            const opts = options;
+            const sub = command;
+            const label = toolActivityLabel(spec.name, spec);
+            const spinner = createSpinner(`${label} · 处理中…`);
+            if (process.stderr.isTTY)
+                spinner.start();
+            const merged = enrichUploadParamsIfNeeded(spec.name, opts);
+            const invoker = new ToolInvoker();
+            const result = await invoker.invoke(spec.name, merged, {
+                async: spec.async && !!opts.async,
+                timeout: spec.timeout,
+            });
+            if (process.stderr.isTTY) {
+                if (result.status === "completed")
+                    spinner.succeed(`${label} · 已完成`);
+                else if (result.status === "failed")
+                    spinner.fail(`${label} · 失败`);
+                else
+                    spinner.stop();
+            }
+            const format = resolveInvokeOutputFormat(sub.parent ?? sub);
+            if (shouldEmitEnvelope(format)) {
+                emitJson(wrapEnvelope(result, { command: `tools ${commandName}`, tool_id: spec.name }));
+            }
+            else {
+                formatOutput(result, format, { activityLabel: label });
+            }
+        })(...args);
+    }));
+    appendToolQuickExample(cmd, spec.name);
+}
+const TOOLS_HELP = `
+gd-cli tools <command> [options]
+
+用于调用一个独立能力，例如图片生成、抠图、高清化、标题生成、提示词扩写、视频生成。
+如果你要完成完整业务场景，请优先查看 workflows。
+
+常用命令:
+  list/ls                   列出内置 Tools
+  info <tool-id>            查看具体 Tool 详情
+  call <tool-id>            调用具体 Tool 能力
+  manifest                  输出 Tools 能力清单
+  schema <tool-id>          查看输入/输出 Schema
+  examples <tool-id>        查看调用示例  
+
+分类:
+  image                     生图、抠图、高清化、SVG
+  video                     文生视频、图生视频
+  text                      标题、提示词、文案
+  asset                     临时上传、CDN URL
+
+示例:
+  gd-cli tools list --category image
+  gd-cli tools info image.generate
+  gd-cli tools schema image.generate
+  gd-cli tools call image.generate --input prompt.json --format json
+`;
+function toPublicToolPayload(tool) {
+    const { endpoint: _endpoint, method: _method, runtime: _runtime, required_env: _requiredEnv, ...publicTool } = tool;
+    return {
+        ...publicTool,
+        ...capabilityMetadata("tool", tool.name),
+        canonical_command: `gd-cli tools call ${tool.name}`,
+        schema_command: `gd-cli tools schema ${tool.name} --format json`,
+        examples_command: `gd-cli tools examples ${tool.name} --format json`,
+    };
+}
+const TOOL_CALL_HELP = `
+
+JSON 输入:
+  gd-cli tools call image.generate --input prompt.json --format json
+  cat prompt.json | gd-cli tools call image.generate - --format json
+  gd-cli tools call text.title --set brief="夏季防晒衣，轻薄透气" --format json
+
+说明:
+  --input <file> 读取 JSON object；位置参数 - 从 stdin 读取 JSON。
+  命令行参数会覆盖 JSON 同名字段。
+`;

package/dist/src/commands/update.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerUpdateCommand(program: Command): void;

package/dist/src/commands/update.js

@@ -0,0 +1,167 @@
+import { spawn } from "node:child_process";
+import chalk from "chalk";
+import { confirm } from "@inquirer/prompts";
+import { withErrorHandler } from "../middleware/error-handler.js";
+import { buildUpdateCommand, detectInstallSource } from "../update/install-source.js";
+import { checkForUpdate, clearUpdateCache } from "../update/update-checker.js";
+import { AgentSkillInstaller } from "../utils/agent-skill-installer.js";
+export function registerUpdateCommand(program) {
+    const update = program
+        .command("update")
+        .description("检查并升级 gd-cli")
+        .option("--channel <tag>", "npm dist-tag: latest / next / alpha", "latest")
+        .option("--manager <name>", "指定包管理器: npm / pnpm / yarn / brew")
+        .option("--dry-run", "只显示升级命令，不执行")
+        .option("-y, --yes", "跳过确认直接升级")
+        .action(withErrorHandler(async (options, command) => {
+        await runUpdate(options, command);
+    }));
+    update
+        .command("check")
+        .description("检查是否有新版本")
+        .option("--channel <tag>", "npm dist-tag: latest / next / alpha", "latest")
+        .option("--force", "忽略 24 小时缓存，强制请求 registry")
+        .action(withErrorHandler(async (options, command) => {
+        const info = await checkForUpdate({
+            channel: options.channel,
+            force: options.force,
+        });
+        printUpdateInfo(info, outputFormat(command));
+    }));
+    update
+        .command("clear-cache")
+        .description("清除本地升级检查缓存")
+        .action(withErrorHandler(async () => {
+        clearUpdateCache();
+        console.log(chalk.green("✓ 已清除升级检查缓存"));
+    }));
+}
+async function runUpdate(options, command) {
+    const info = await checkForUpdate({
+        channel: options.channel,
+        force: true,
+    });
+    const source = detectInstallSource(options.manager);
+    const updateCommand = buildUpdateCommand(info.latest_version, source);
+    const format = outputFormat(command);
+    if (!info.update_available) {
+        printUpdateInfo({ ...info, install_source: source }, format);
+        return;
+    }
+    if (source.kind !== "global") {
+        const payload = {
+            ...info,
+            install_source: source,
+            update_command: updateCommand.display,
+            blocked: true,
+            reason: source.reason,
+        };
+        if (format === "json") {
+            console.log(JSON.stringify(payload, null, 2));
+        }
+        else {
+            console.log(chalk.yellow(`${source.reason}，gd-cli update 不会修改全局环境。`));
+            console.log(`如需升级全局安装，请手动执行: ${chalk.cyan(updateCommand.display)}`);
+        }
+        return;
+    }
+    if (options.dryRun) {
+        printUpdateInfo({
+            ...info,
+            install_source: source,
+        }, format, updateCommand.display);
+        return;
+    }
+    if (!options.yes && process.stdin.isTTY) {
+        const ok = await confirm({
+            message: `将执行 ${updateCommand.display}，是否继续？`,
+            default: true,
+        });
+        if (!ok) {
+            console.log("已取消升级。");
+            return;
+        }
+    }
+    else if (!options.yes && !process.stdin.isTTY) {
+        throw new Error(`非交互环境请加 --yes，或手动执行: ${updateCommand.display}`);
+    }
+    const shouldRefreshAgentSkill = hasInstalledCanonicalSkill();
+    await spawnUpdate(updateCommand.command, updateCommand.args);
+    if (shouldRefreshAgentSkill) {
+        await refreshAgentSkillAfterUpdate();
+    }
+}
+function printUpdateInfo(info, format, updateCommand) {
+    if (format === "json") {
+        console.log(JSON.stringify({
+            ...info,
+            update_command: updateCommand ?? buildUpdateCommand(info.latest_version, info.install_source).display,
+        }, null, 2));
+        return;
+    }
+    console.log(chalk.bold("\ngd-cli 版本检查\n"));
+    console.log(`  当前版本: ${chalk.cyan(info.current_version)}`);
+    console.log(`  最新版本: ${chalk.cyan(info.latest_version)} (${info.channel})`);
+    console.log(`  Registry: ${chalk.dim(info.registry)}`);
+    console.log(`  安装方式: ${info.install_source.manager} / ${info.install_source.kind}`);
+    if (info.unavailable_reason === "package_not_found") {
+        console.log(chalk.yellow("\n  当前 registry 暂未找到该包，已跳过自动升级检查"));
+        console.log("");
+        return;
+    }
+    if (info.update_available) {
+        const cmd = updateCommand ?? buildUpdateCommand(info.latest_version, info.install_source).display;
+        console.log(chalk.yellow("\n  有新版本可用"));
+        console.log(`  升级命令: ${chalk.cyan(cmd)}`);
+    }
+    else {
+        console.log(chalk.green("\n  已是最新版本"));
+    }
+    console.log("");
+}
+function outputFormat(command) {
+    return rootCommand(command).opts().format ?? "human";
+}
+function rootCommand(command) {
+    let cur = command;
+    while (cur.parent)
+        cur = cur.parent;
+    return cur;
+}
+function spawnUpdate(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: "inherit",
+        });
+        child.on("error", reject);
+        child.on("exit", (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`升级命令退出码: ${code}`));
+            }
+        });
+    });
+}
+async function refreshAgentSkillAfterUpdate() {
+    try {
+        await spawnUpdate("gd-cli", ["skills", "update"]);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.yellow(`gd-cli 已升级，但 Agent Skill 自动刷新失败：${message}`));
+        console.error(chalk.dim("可稍后手动执行: gd-cli skills update"));
+    }
+}
+function hasInstalledCanonicalSkill() {
+    try {
+        const canonical = new AgentSkillInstaller()
+            .status()
+            .targets.find((target) => target.agent === "universal");
+        return canonical?.status === "installed" || canonical?.status === "outdated";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/commands/usage.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from "commander";
+import { UsageClient } from "../api/usage-client.js";
+interface UsageCommandDeps {
+    createClient?: () => Pick<UsageClient, "getCreditsOverview">;
+}
+export declare function registerUsageCommand(program: Command, deps?: UsageCommandDeps): void;
+export {};

package/dist/src/commands/usage.js

@@ -0,0 +1,43 @@
+import chalk from "chalk";
+import { UsageClient } from "../api/usage-client.js";
+import { withErrorHandler } from "../middleware/error-handler.js";
+import { formatOutput } from "../middleware/output.js";
+export function registerUsageCommand(program, deps = {}) {
+    program
+        .command("usage", { hidden: true })
+        .description("Agent internal usage and entitlement probe")
+        .action(withErrorHandler(async (_options, command) => {
+        const client = deps.createClient?.() ?? new UsageClient();
+        const payload = await client.getCreditsOverview();
+        const format = outputFormat(command);
+        if (format === "json") {
+            formatOutput(payload, "json");
+            return;
+        }
+        printUsageHuman(payload);
+    }));
+}
+function printUsageHuman(payload) {
+    const { organization, credits } = payload;
+    console.log(chalk.bold("稿豆余额"));
+    console.log(`  当前组织: ${organization.name ?? organization.id} (${organization.id})`);
+    console.log(`  剩余稿豆: ${credits.surplus}`);
+    console.log(`  总额:     ${credits.total}`);
+    console.log(`  已使用:   ${credits.used}`);
+    if (credits.wait)
+        console.log(`  待生效:   ${credits.wait}`);
+    console.log("");
+}
+function outputFormat(command) {
+    const root = rootCommand(command);
+    const opts = root.opts();
+    if (opts.json)
+        return "json";
+    return opts.format ?? "human";
+}
+function rootCommand(command) {
+    let current = command;
+    while (current.parent)
+        current = current.parent;
+    return current;
+}

package/dist/src/commands/workflows.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerWorkflowsCommand(program: Command): void;
+export declare function runAppCall(appId: string, inputRef: string | undefined, opts: Record<string, unknown>, cmd: Command): Promise<void>;