gaoding-cli 1.0.0-alpha.5

package/dist/src/registry/agent-contracts.js

@@ -0,0 +1,483 @@
+import { CLI_VERSION } from "../utils/config.js";
+import { DIRECT_APPS, PUBLIC_DIRECT_TOOLS, appToolDependencies, appsDependingOnTool, resolveAppSpec, resolvePublicToolSpec, } from "./direct-registry.js";
+import { capabilityMetadata, } from "../utils/capability-metadata.js";
+export function buildInputJsonSchema(params, extraProperties = {}) {
+    const properties = { ...extraProperties };
+    const required = [];
+    for (const param of params) {
+        const prop = {
+            type: param.type === "file" ? "string" : param.type,
+            description: param.description,
+            "x-cli-flag": param.cli_flag,
+        };
+        if (param.type === "file")
+            prop.format = "uri-reference";
+        if (param.default !== undefined)
+            prop.default = param.default;
+        if (param.enum)
+            prop.enum = param.enum;
+        properties[param.name] = prop;
+        if (param.required)
+            required.push(param.name);
+    }
+    return {
+        type: "object",
+        properties,
+        required,
+        additionalProperties: true,
+    };
+}
+export function buildOutputJsonSchema(output) {
+    const properties = {};
+    for (const [key, prop] of Object.entries(output.properties ?? {})) {
+        properties[key] = {
+            type: prop.type,
+            description: prop.description,
+        };
+    }
+    return {
+        type: "object",
+        properties,
+        required: [],
+        additionalProperties: true,
+    };
+}
+export function buildToolSchema(toolId) {
+    const spec = resolvePublicToolSpec(toolId);
+    if (!spec)
+        throw new Error(`未找到工具: ${toolId}`);
+    const input = sampleInput(spec.input ?? []);
+    return {
+        id: spec.name,
+        type: "tool",
+        category: spec.category,
+        title: spec.display_name,
+        description: spec.description,
+        canonical_command: `gd-cli tools call ${spec.name}`,
+        schema_command: `gd-cli tools schema ${spec.name} --format json`,
+        examples_command: `gd-cli tools examples ${spec.name} --format json`,
+        input_schema: buildInputJsonSchema(spec.input ?? []),
+        output_schema: buildOutputJsonSchema(spec.output),
+        sample_input: input,
+        stdin: {
+            supported: true,
+            command: `cat input.json | gd-cli tools call ${spec.name} - --format json`,
+            content_type: "application/json",
+        },
+    };
+}
+export function buildWorkflowSchema(appId) {
+    const spec = resolveAppSpec(appId);
+    if (!spec)
+        throw new Error(`未找到应用: ${appId}`);
+    const input = sampleInput(spec.input ?? []);
+    return {
+        id: spec.id,
+        type: "workflow",
+        category: spec.category,
+        title: spec.name,
+        description: spec.description,
+        canonical_command: `gd-cli workflows run ${spec.id}`,
+        schema_command: `gd-cli workflows schema ${spec.id} --format json`,
+        examples_command: `gd-cli workflows examples ${spec.id} --format json`,
+        input_schema: buildInputJsonSchema(spec.input ?? []),
+        output_schema: buildOutputJsonSchema(spec.output),
+        sample_input: input,
+        deliverables: spec.outputs ?? ["manifest.json", "README.md", "assets/"],
+        stdin: {
+            supported: true,
+            command: `cat brief.json | gd-cli workflows run ${spec.id} - --format json`,
+            content_type: "application/json",
+        },
+    };
+}
+export function buildToolExamples(toolId) {
+    const spec = resolvePublicToolSpec(toolId);
+    if (!spec)
+        throw new Error(`未找到工具: ${toolId}`);
+    const input = sampleInput(spec.input ?? []);
+    const curatedExamples = curatedToolExamples(spec.name);
+    const agentInput = firstExampleInput(curatedExamples) ?? input;
+    return {
+        id: spec.name,
+        type: "tool",
+        category: spec.category,
+        title: spec.display_name,
+        description: spec.description,
+        examples: [
+            ...(curatedExamples.length > 0
+                ? curatedExamples
+                : [
+                    scenarioExample(spec.description, buildFlagCommand("gd-cli tools call", spec.name, spec.input ?? []), input),
+                ]),
+            {
+                description: "Agent / 脚本推荐：stdin JSON",
+                command: `cat input.json | gd-cli tools call ${spec.name} - --format json`,
+                input_json: agentInput,
+            },
+            {
+                description: "Agent / 脚本推荐：JSON 文件",
+                command: `gd-cli tools call ${spec.name} --input input.json --format json`,
+                input_json: agentInput,
+            },
+        ],
+    };
+}
+export function buildWorkflowExamples(appId) {
+    const spec = resolveAppSpec(appId);
+    if (!spec)
+        throw new Error(`未找到应用: ${appId}`);
+    const input = sampleInput(spec.input ?? []);
+    const curatedExamples = curatedAppExamples(spec.id);
+    const agentInput = firstExampleInput(curatedExamples) ?? input;
+    const examples = [
+        ...(curatedExamples.length > 0
+            ? curatedExamples
+            : [
+                scenarioExample(spec.description, spec.examples?.[0] ?? buildFlagCommand("gd-cli workflows run", spec.id, spec.input ?? []), input),
+            ]),
+        {
+            description: "Agent / 脚本推荐：stdin JSON",
+            command: `cat brief.json | gd-cli workflows run ${spec.id} - --format json`,
+            input_json: agentInput,
+        },
+        {
+            description: "Agent / 脚本推荐：JSON 文件",
+            command: `gd-cli workflows run ${spec.id} --input brief.json --format json`,
+            input_json: agentInput,
+        },
+    ];
+    if (spec.supports_batch) {
+        examples.push({
+            description: "批量任务 dry-run 预检",
+            command: `gd-cli workflows run ${spec.id} --input ./products.csv --assets-dir ./images --dry-run --format json`,
+        });
+    }
+    return {
+        id: spec.id,
+        type: "workflow",
+        category: spec.category,
+        title: spec.name,
+        description: spec.description,
+        examples,
+    };
+}
+export function buildManifest(scope = "all") {
+    const commands = [];
+    if (scope === "all" || scope === "tools") {
+        commands.push(...PUBLIC_DIRECT_TOOLS.map(toolManifestCommand));
+    }
+    if (scope === "all" || scope === "workflows") {
+        commands.push(...DIRECT_APPS.map(workflowManifestCommand));
+    }
+    if (scope === "all") {
+        commands.push({
+            id: "dam.upload",
+            type: "dam",
+            category: "asset",
+            title: "DAM 素材上传",
+            description: "上传本地文件到 DAM，返回可复用 asset_id 与 CDN URL",
+            canonical_command: "gd-cli dam upload <file>",
+            output: "json",
+            safe_for_agent: true,
+            ...capabilityMetadata("dam", "dam.upload"),
+        }, {
+            id: "dam.search",
+            type: "dam",
+            category: "asset",
+            title: "DAM 素材搜索",
+            description: "按关键词、资源库、文件夹、类型、格式或标签搜索素材",
+            canonical_command: "gd-cli dam search <keyword>",
+            output: "json",
+            safe_for_agent: true,
+            ...capabilityMetadata("dam", "dam.search"),
+        }, {
+            id: "org.current",
+            type: "org",
+            category: "account",
+            title: "当前组织",
+            description: "查询当前绑定团队，便于 Agent 确认执行上下文",
+            canonical_command: "gd-cli org current",
+            output: "json",
+            safe_for_agent: true,
+            ...capabilityMetadata("org", "org.current"),
+        });
+    }
+    return {
+        name: "gd-cli",
+        version: CLI_VERSION,
+        description: "Gaoding creative production CLI for agents",
+        commands,
+    };
+}
+export function rowsForManifest(manifest) {
+    return manifest.commands.map((command) => ({
+        id: command.id,
+        type: command.type,
+        分类: command.category,
+        名称: command.title,
+        command: command.canonical_command,
+    }));
+}
+export function buildTopExamples() {
+    return {
+        examples: [
+            {
+                title: "生成商品图库素材包",
+                description: "完整 Workflow：上传商品图，自动完成抠图、提示词优化、多图生成和标题卖点整理，适合要一组可上架 Listing 图库时使用。",
+                command: "gd-cli workflows run listing-gallery --image ./sku_001.jpg --brief \"夏季轻薄防晒衣，透气面料，适合户外通勤；卖点图短文案：轻薄防晒 通勤无负担\" --copy-mode render-text --ratio 1:1 -f json",
+                input_json: {
+                    image: "./sku_001.jpg",
+                    brief: "夏季轻薄防晒衣，透气面料，适合户外通勤；卖点图短文案：轻薄防晒 通勤无负担",
+                    copy_mode: "render-text",
+                    ratio: "1:1",
+                },
+            },
+            {
+                title: "单项 AI 生图",
+                description: "只调用生图 Tool，不编排完整 Workflow；适合已有明确画面提示词，只需要一张图时使用。",
+                command: "gd-cli tools call image.generate --prompt \"电商主图，白底，突出夏季轻薄防晒衣的透气面料，干净高级\" --image ./sku_001.jpg --ratio 1:1 -f json",
+                input_json: {
+                    prompt: "电商主图，白底，突出夏季轻薄防晒衣的透气面料，干净高级",
+                    image: "./sku_001.jpg",
+                    ratio: "1:1",
+                },
+            },
+            {
+                title: "生成商品标题",
+                description: "轻量文本 Tool；适合脚本或 Agent 批量根据 brief 生成标题。",
+                command: "gd-cli tools call text.title --brief \"夏季轻薄防晒衣，防晒透气，户外通勤，女款\" -f json",
+                input_json: {
+                    brief: "夏季轻薄防晒衣，防晒透气，户外通勤，女款",
+                },
+            },
+            {
+                title: "生成商品短视频",
+                description: "文生视频；适合没有参考图、先用文字描述生成短视频镜头。",
+                command: "gd-cli tools call video.generate --prompt \"商品短视频，展示夏季轻薄防晒衣的透气面料和户外通勤场景，镜头缓慢推进\" --duration 5 -f json",
+                input_json: {
+                    prompt: "商品短视频，展示夏季轻薄防晒衣的透气面料和户外通勤场景，镜头缓慢推进",
+                    duration: "5",
+                },
+            },
+            {
+                title: "参考图生成商品短视频",
+                description: "图生视频；适合以商品图作为首帧或视觉参考，保持商品主体一致。",
+                command: "gd-cli tools call video.generate --prompt \"以参考图为首帧，展示防晒衣面料细节，轻微镜头推进，自然光\" --image ./sku_001.jpg --duration 5 -f json",
+                input_json: {
+                    prompt: "以参考图为首帧，展示防晒衣面料细节，轻微镜头推进，自然光",
+                    image: "./sku_001.jpg",
+                    duration: "5",
+                },
+            },
+            {
+                title: "查找 DAM 里的商品素材",
+                description: "搜索已入库素材，返回 asset_id、URL、封面和文件信息，适合后续 Workflow / Tool 复用素材。",
+                command: "gd-cli dam search \"防晒衣\" --type image --format jpg,png -f json",
+            },
+            {
+                title: "Agent 读取能力清单",
+                description: "机器可读入口；Agent 应优先读取 manifest，再按 schema/examples 选择能力和拼装参数。",
+                command: "gd-cli manifest -f json",
+            },
+        ],
+    };
+}
+function toolManifestCommand(spec) {
+    return {
+        id: spec.name,
+        type: "tool",
+        category: spec.category,
+        title: spec.display_name,
+        description: spec.description,
+        canonical_command: `gd-cli tools call ${spec.name}`,
+        input_schema_command: `gd-cli tools schema ${spec.name}`,
+        examples_command: `gd-cli tools examples ${spec.name}`,
+        output: "json",
+        safe_for_agent: true,
+        ...capabilityMetadata("tool", spec.name),
+        affected_workflows: appsDependingOnTool(spec.name).map((app) => app.id),
+    };
+}
+function workflowManifestCommand(spec) {
+    return {
+        id: spec.id,
+        type: "workflow",
+        category: spec.category,
+        title: spec.name,
+        description: spec.description,
+        canonical_command: `gd-cli workflows run ${spec.id}`,
+        input_schema_command: `gd-cli workflows schema ${spec.id}`,
+        examples_command: `gd-cli workflows examples ${spec.id}`,
+        output: "json",
+        safe_for_agent: true,
+        ...capabilityMetadata("app", spec.id),
+        dependency_tools: appToolDependencies(spec),
+    };
+}
+function buildFlagCommand(prefix, id, params) {
+    const pieces = [prefix, id];
+    for (const param of params) {
+        if (!param.required)
+            continue;
+        pieces.push(param.cli_flag, quoteShell(String(sampleValue(param))));
+    }
+    pieces.push("--format", "json");
+    return pieces.join(" ");
+}
+function sampleInput(params) {
+    const out = {};
+    for (const param of params) {
+        if (!param.required && param.default === undefined)
+            continue;
+        out[param.name] = sampleValue(param);
+    }
+    return out;
+}
+function sampleValue(param) {
+    if (param.default !== undefined)
+        return param.default;
+    const name = param.name.toLowerCase();
+    if (param.type === "boolean")
+        return true;
+    if (param.type === "number")
+        return 1;
+    if (name.includes("image"))
+        return "./sku.png";
+    if (name.includes("assets_dir"))
+        return "./images";
+    if (name === "input")
+        return "./products.csv";
+    if (name.includes("duration"))
+        return "5";
+    if (name.includes("ratio"))
+        return "1:1";
+    if (name.includes("brief"))
+        return "夏季防晒衣，轻薄透气，适合户外通勤";
+    if (name.includes("prompt"))
+        return "生成一张干净高级的电商商品主图";
+    if (name.includes("file"))
+        return "./image.png";
+    return "value";
+}
+function curatedToolExamples(toolId) {
+    if (toolId === "asset.upload") {
+        return [
+            scenarioExample("上传本地商品图到临时 CDN，返回可传给后续 Tool/App 的 URL。", "gd-cli tools call asset.upload --file ./sku_001.jpg -f json", { file: "./sku_001.jpg" }),
+        ];
+    }
+    if (toolId === "text.title") {
+        return [
+            scenarioExample("根据商品卖点生成适合电商或社媒使用的标题。", "gd-cli tools call text.title --brief \"夏季轻薄防晒衣，防晒透气，户外通勤，女款\" -f json", { brief: "夏季轻薄防晒衣，防晒透气，户外通勤，女款" }),
+        ];
+    }
+    if (toolId === "text.prompt") {
+        return [
+            scenarioExample("把简短商品需求扩写成更适合生图模型的提示词。", "gd-cli tools call text.prompt --prompt \"防晒衣电商主图，突出轻薄透气\" --image ./sku_001.jpg -f json", {
+                prompt: "防晒衣电商主图，突出轻薄透气",
+                image: "./sku_001.jpg",
+            }),
+        ];
+    }
+    if (toolId === "image.cutout") {
+        return [
+            scenarioExample("商品图抠图，输出透明背景 PNG，适合后续主图或海报合成。", "gd-cli tools call image.cutout --image ./sku_001.jpg --mode product -f json", { image: "./sku_001.jpg", mode: "product" }),
+        ];
+    }
+    if (toolId === "image.generate") {
+        return [
+            scenarioExample("不带参考图，直接根据文字提示词生成一张电商海报。", "gd-cli tools call image.generate --prompt \"夏季轻薄防晒衣电商海报，清爽户外通勤场景，自然光，干净高级，突出轻薄透气面料\" --ratio 1:1 -f json", {
+                prompt: "夏季轻薄防晒衣电商海报，清爽户外通勤场景，自然光，干净高级，突出轻薄透气面料",
+                ratio: "1:1",
+            }),
+            scenarioExample("带参考图，根据商品图和提示词生成一张干净高级的电商主图。", "gd-cli tools call image.generate --prompt \"电商主图，白底，突出夏季轻薄防晒衣的透气面料，干净高级\" --image ./sku_001.jpg --ratio 1:1 -f json", {
+                prompt: "电商主图，白底，突出夏季轻薄防晒衣的透气面料，干净高级",
+                image: "./sku_001.jpg",
+                ratio: "1:1",
+            }),
+        ];
+    }
+    if (toolId === "image.svg") {
+        return [
+            scenarioExample("把 Logo 或图形素材转成 SVG，适合后续编辑或排版。", "gd-cli tools call image.svg --image ./logo.png --mode auto -f json", { image: "./logo.png", mode: "auto" }),
+        ];
+    }
+    if (toolId === "image.super-res") {
+        return [
+            scenarioExample("提升商品图清晰度，适合上架前处理低清素材。", "gd-cli tools call image.super-res --image ./sku_001.jpg --mode hd -f json", { image: "./sku_001.jpg", mode: "hd" }),
+        ];
+    }
+    if (toolId === "video.generate") {
+        return [
+            scenarioExample("文生视频：没有参考图时，直接用镜头描述生成商品短视频。", "gd-cli tools call video.generate --prompt \"商品短视频，展示夏季轻薄防晒衣的透气面料和户外通勤场景，镜头缓慢推进\" --duration 5 -f json", {
+                prompt: "商品短视频，展示夏季轻薄防晒衣的透气面料和户外通勤场景，镜头缓慢推进",
+                duration: "5",
+            }),
+            scenarioExample("图生视频：以商品图为首帧或视觉参考，保持商品主体一致。", "gd-cli tools call video.generate --prompt \"以参考图为首帧，展示防晒衣面料细节，轻微镜头推进，自然光\" --image ./sku_001.jpg --duration 5 -f json", {
+                prompt: "以参考图为首帧，展示防晒衣面料细节，轻微镜头推进，自然光",
+                image: "./sku_001.jpg",
+                duration: "5",
+            }),
+        ];
+    }
+    return [];
+}
+function curatedAppExamples(appId) {
+    if (appId === "listing-gallery") {
+        return [
+            scenarioExample("生成一套可上架的商品图库素材，包含白底主图、卖点图、细节图和生活方式图。", "gd-cli workflows run listing-gallery --image ./sku_001.jpg --brief \"夏季轻薄防晒衣，透气面料，适合户外通勤；卖点图短文案：轻薄防晒 通勤无负担\" --copy-mode render-text --ratio 1:1 -f json", {
+                image: "./sku_001.jpg",
+                brief: "夏季轻薄防晒衣，透气面料，适合户外通勤；卖点图短文案：轻薄防晒 通勤无负担",
+                copy_mode: "render-text",
+                ratio: "1:1",
+            }),
+        ];
+    }
+    if (appId === "pdp-a-plus") {
+        return [
+            scenarioExample("生成详情页/A+模块素材，按购买疑虑组织首屏、痛点、结构、使用和规格模块。", "gd-cli workflows run pdp-a-plus --image ./air-purifier.jpg --brief \"桌面空气净化器，静音，滤芯可更换，适合卧室；首屏短文案：静音净化 安心入睡\" --copy-mode render-text --ratio 4:5 -f json", {
+                image: "./air-purifier.jpg",
+                brief: "桌面空气净化器，静音，滤芯可更换，适合卧室；首屏短文案：静音净化 安心入睡",
+                copy_mode: "render-text",
+                ratio: "4:5",
+            }),
+        ];
+    }
+    if (appId === "social-seeding-pack") {
+        return [
+            scenarioExample("生成小红书种草图文素材，包含封面图、场景图、标题、正文和标签。", "gd-cli workflows run social-seeding-pack --image ./serum.jpg --brief \"屏障修护精华，清爽不黏，适合通勤包分享；封面短文案：通勤包里的清爽修护\" --copy-mode render-text --ratio 3:4 -f json", {
+                image: "./serum.jpg",
+                brief: "屏障修护精华，清爽不黏，适合通勤包分享；封面短文案：通勤包里的清爽修护",
+                copy_mode: "render-text",
+                ratio: "3:4",
+            }),
+        ];
+    }
+    if (appId === "campaign-kv-pack") {
+        return [
+            scenarioExample("生成 Campaign KV 多渠道素材，包含横版、方图、竖图和渠道裁切建议。", "gd-cli workflows run campaign-kv-pack --image ./running-shoes.jpg --brief \"城市跑鞋新品 Campaign，轻量缓震，面向通勤跑者；主标题：轻跑进城\" --copy-mode render-text --ratios 16:9,1:1,4:5 -f json", {
+                image: "./running-shoes.jpg",
+                brief: "城市跑鞋新品 Campaign，轻量缓震，面向通勤跑者；主标题：轻跑进城",
+                copy_mode: "render-text",
+                ratios: "16:9,1:1,4:5",
+            }),
+        ];
+    }
+    return [];
+}
+function scenarioExample(description, command, inputJson) {
+    return {
+        description,
+        command,
+        ...(inputJson ? { input_json: inputJson } : {}),
+    };
+}
+function firstExampleInput(examples) {
+    const input = examples.find((item) => item.input_json)?.input_json;
+    return input && typeof input === "object" && !Array.isArray(input)
+        ? input
+        : undefined;
+}
+function quoteShell(value) {
+    return /^[\w./:=,-]+$/.test(value) ? value : `"${value.replace(/"/g, '\\"')}"`;
+}

package/dist/src/registry/app-loader.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function loadDynamicAppCommands(appCmd: Command): Promise<void>;

package/dist/src/registry/app-loader.js

@@ -0,0 +1,70 @@
+import { RegistryCache } from "./registry-cache.js";
+import { RegistryClient } from "./registry-client.js";
+import { HubClient } from "../api/hub-client.js";
+import { AppRunner } from "../api/app-runner.js";
+import { withAuth } from "../middleware/auth.js";
+import { withErrorHandler } from "../middleware/error-handler.js";
+import { formatOutput } from "../middleware/output.js";
+import { resolveInvokeOutputFormat } from "../utils/list-output-format.js";
+import { appActivityLabel } from "../utils/tool-display.js";
+import { createSpinner } from "../utils/spinner.js";
+import { logger } from "../utils/logger.js";
+export async function loadDynamicAppCommands(appCmd) {
+    const client = new HubClient();
+    const registryClient = new RegistryClient(client);
+    const cache = new RegistryCache(registryClient);
+    let registry;
+    try {
+        registry = await cache.get();
+    }
+    catch {
+        logger.debug("Registry 缓存不可用，跳过动态 APP 命令注册");
+        return;
+    }
+    const apps = registry.apps ?? [];
+    for (const app of apps) {
+        registerAppSubcommand(appCmd, app);
+    }
+}
+function registerAppSubcommand(parent, spec) {
+    const cmd = parent
+        .command(spec.id)
+        .description(spec.description);
+    for (const param of spec.input ?? []) {
+        const flag = param.cli_flag ?? `--${param.name}`;
+        const desc = param.description + (param.required ? " (必填)" : "");
+        cmd.option(`${flag} <value>`, desc);
+    }
+    cmd
+        .option("--async", "异步模式", false)
+        .option("--timeout <seconds>", "超时时间（秒）", String(spec.estimated_duration * 2))
+        .action(withErrorHandler(withAuth(async (...args) => {
+        const opts = args[0];
+        const cmd = args[1];
+        const params = {};
+        for (const [k, v] of Object.entries(opts)) {
+            if (k !== "async" && k !== "timeout" && v !== undefined && v !== false) {
+                params[k] = v;
+            }
+        }
+        const label = appActivityLabel(spec.id, spec.name);
+        const spinner = createSpinner(`${label} · 处理中…`);
+        if (process.stderr.isTTY)
+            spinner.start();
+        const runner = new AppRunner();
+        const result = await runner.run(spec.id, params, {
+            async: !!opts.async,
+            timeout: parseInt(String(opts.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);
+        formatOutput(result, format, { activityLabel: label });
+    })));
+}

package/dist/src/registry/direct-registry.d.ts

@@ -0,0 +1,11 @@
+import type { AppSpec, RegistryResponse, ToolSpec } from "./types.js";
+export declare const DIRECT_TOOLS: ToolSpec[];
+export declare const PUBLIC_DIRECT_TOOLS: ToolSpec[];
+export declare const DIRECT_APPS: AppSpec[];
+export declare const DIRECT_REGISTRY: RegistryResponse;
+export declare function resolveToolSpec(id: string): ToolSpec | undefined;
+export declare function resolvePublicToolSpec(id: string): ToolSpec | undefined;
+export declare function isPublicToolSpec(tool: ToolSpec): boolean;
+export declare function resolveAppSpec(id: string): AppSpec | undefined;
+export declare function appToolDependencies(app: AppSpec): string[];
+export declare function appsDependingOnTool(toolId: string): AppSpec[];