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

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.0.0-alpha.9] - 2026-08-01
+
+### Changed
+
+- 根命令仅保留 `--version` 和 `--help`，机器可读的 `--json` 收敛到确有脚本消费价值的叶子命令。
+- `skills install` 与 `skills uninstall` 在未指定目标时默认处理全部 Agent，且不再二次确认；`update` 收敛为无选项动作。
+- Creative 使用语义化的 `question_message_id`，并收紧输入、输出 Schema 与错误响应契约。
+- Workflow 固定内部并发为 2，并由 CLI 选项显式授权敏感路径。
+
+### Removed
+
+- 删除根级 `--format`、`--json`、`--no-input` 和 `--yes`，以及不再具有明确语义的重复输出选项。
+
+### Security
+
+- DAM 公开结果改为白名单 DTO，并过滤私网地址、危险协议、userinfo 与敏感查询参数。
+- 公共错误响应改为字段白名单，不再透传后端 `detail` 或内部 Tool/App 路由信息。
+
 ## [1.0.0-alpha.8] - 2026-08-01
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # gaoding-cli
 
-GD CLI 是稿定设计能力的命令行入口，为用户、脚本、CI 和 Agent 提供登录、组织切换、统一 Creative 创作、多步骤 Workflow 和 DAM 素材管理能力。
+GD CLI 是稿定设计能力的命令行入口，为用户、脚本、CI 和 Agent 提供认证、组织切换、统一 Creative 创作、多步骤 Workflow 和 DAM 素材管理。
 
 ## Requirements
 
@@ -9,95 +9,91 @@ GD CLI 是稿定设计能力的命令行入口，为用户、脚本、CI 和 Age
 
 ## Installation
 
-默认使用全局安装：
-
 ```bash
 npm install -g gaoding-cli
 gd-cli skills install
 gd-cli auth login
 ```
 
-Agent 的安装与接入规则以[官方 Agent 安装文档](https://www.gaoding.com/cli/install.md)为准。
+`npm install -g gaoding-cli` 只安装 CLI。执行 `gd-cli skills install` 才会安装 Agent Skill；不传参数时安装到全部已知 Agent target。详细规则见[官方 Agent 安装文档](https://www.gaoding.com/cli/install.md)。
 
-非交互 Agent 或 CI 需要显式指定目标并完成确认：
+在 Agent 或 CI 中，可指定一个或多个 target；安装和卸载均为人类可读输出，用 `skills status --json` 检查机器状态：
 
 ```bash
-gd-cli skills install --agent codex --yes --format json
-gd-cli auth login --no-browser --format json
+gd-cli skills install --agent codex
+gd-cli skills status --json
+gd-cli auth login --no-browser
 ```
 
-`npm install -g gaoding-cli` 只安装 CLI，不会修改任何 Agent 目录。只有显式执行 `gd-cli skills install` 才会安装 Agent Skill。
-
 ## Quick Start
 
 ```bash
-gd-cli auth status
-
-gd-cli org list
+gd-cli auth status --json
+gd-cli org list --json
 gd-cli org switch --org <org-id>
 
-gd-cli creative schema --format json
-gd-cli creative examples --format json
-gd-cli creative run --prompt "为夏季运动鞋生成一张户外通勤广告图" --format json
+gd-cli creative schema --json
+gd-cli creative examples
+gd-cli creative run --prompt "为夏季运动鞋生成一张户外通勤广告图" --json
 
-gd-cli workflows list
+gd-cli workflows list --json
 gd-cli workflows run listing-gallery \
   --image ./product.jpg \
-  --brief "夏季运动鞋，轻量缓震，适合通勤"
+  --brief "夏季运动鞋，轻量缓震，适合通勤" \
+  --json
 
-gd-cli dam upload ./product.jpg
+gd-cli dam upload ./product.jpg --json
 ```
 
 ## Commands
 
+使用 `gd-cli --help` 查看一级命令，再使用 `gd-cli <command> --help` 查看子命令和选项。
+
 | Command | Purpose |
 | --- | --- |
-| `auth` | 登录、退出和查看本地认证状态 |
-| `org` | 查看和切换当前组织 |
-| `creative` | 统一发起图片、视频和文本创作 |
-| `workflows` | 运行多步骤创意生产流程 |
-| `skills` | 安装和管理 `gd-cli` Agent Skill |
-| `dam` | 上传、查询和删除 DAM 素材 |
-| `update` | 检查和升级全局 CLI |
-| `org credits` | 查询当前组织稿豆余额 |
+| `auth login [--no-browser]` | 登录；输出面向人 |
+| `auth logout` | 退出登录；输出面向人 |
+| `auth status --json` | 查询认证状态 |
+| `org list/current/credits --json` | 查询组织和稿豆余额 |
+| `org switch [--org]` | 切换组织；输出面向人 |
+| `creative run [--prompt|--input] [--json]` | 发起或继续创作 |
+| `creative schema [--json]` | 查看创作 Schema |
+| `creative examples` | 查看完整可运行示例 |
+| `workflows list [--json]` | 列出 Workflow |
+| `workflows schema <workflow-id> [--json]` | 查看 Workflow Schema |
+| `workflows examples <workflow-id>` | 查看完整可运行示例 |
+| `workflows run <workflow-id> [--json]` | 执行 Workflow |
+| `skills install/uninstall [--agent <id> | --all]` | 管理 Agent Skill |
+| `skills status --json` | 查询 Skill 状态 |
+| `skills update` | 刷新已安装 Skill |
+| `dam upload/list/search/get --json` | 管理和查询素材 |
+| `dam delete` | 删除素材；输出面向人 |
+| `update` | 检查并升级全局 CLI |
+
+默认不会因为 stdin/stdout 不是 TTY 而切换为 JSON。只有支持 `--json` 的叶命令在显式传入该选项时才输出机器可读结果。
 
 ## Agent And Script Usage
 
-核心命令支持 `--format json`，便于脚本和 Agent 解析。Creative 接收目标描述、媒体、结构化约束和连续会话信息，由 GD Agent 理解并完成创作；CLI 对使用者表现为一次输入、一次最终输出。
-
-Creative 的完整输入和输出结构使用本地静态 Schema 发现：
+Creative 使用 `--prompt` 或 `--input`。媒体、结构化约束或连续会话输入使用 JSON 文件或 stdin：
 
 ```bash
-gd-cli creative schema --format json
-gd-cli creative examples --format json
+gd-cli creative run --prompt "为夏季运动鞋生成三条简洁的电商标题" --json
+gd-cli creative run --input creative-request.json --json
+cat creative-request.json | gd-cli creative run --input - --json
 ```
 
-纯文本请求可以直接使用 `--prompt`；包含媒体、`parameters` 或连续会话信息时使用 JSON 输入：
+遇到 `finish_reason=requires_input` 时，回传结果中的 `conversation_id`、`question_message_id` 和 `answers`。完整字段由 `gd-cli creative schema --json` 定义。
 
-```bash
-gd-cli creative run --prompt "为夏季运动鞋生成三条简洁的电商标题" --format json
-gd-cli creative run --input creative-request.json --format json
-cat creative-request.json | gd-cli creative run --input - --format json
-```
-
-多步骤交付使用 `workflows run`：
-
-```bash
-gd-cli workflows run listing-gallery \
-  --image ./product.jpg \
-  --brief "运动鞋上架素材包" \
-  --output-dir ./output \
-  --format json
-```
+Workflow 的可用场景可通过 `gd-cli workflows list --json` 查看；特定输入/输出通过 `gd-cli workflows schema <workflow-id> --json` 查看。
 
 ## Agent Skill
 
-`gd-cli skills install` 将静态 Skill 安装到 `~/.agents/skills/gd-cli`，再为选中的 Agent 创建 link。常用维护命令：
+`gd-cli skills install` 将静态 Skill 安装到 `~/.agents/skills/gd-cli`，并为选择的 Agent 创建链接。常用维护命令：
 
 ```bash
-gd-cli skills status --format json
+gd-cli skills status --json
 gd-cli skills update
-gd-cli skills uninstall --all --yes
+gd-cli skills uninstall --all
 ```
 
 CLI 全局升级后，只在 canonical Skill 已安装时自动刷新它；本地项目安装、`npm link` 和 `npx` 运行不会修改全局 CLI。
@@ -109,23 +105,10 @@ npm install
 npm run build
 npm test
 npm run start -- --help
-```
-
-本地开发使用独立的 `gd-cli-dev`：
-
-```bash
-npm run dev:setup
-npm run dev
-gd-cli-dev --help
-```
-
-默认 smoke test 不登录、不调用付费生成能力：
-
-```bash
 npm run smoke:cli
 ```
 
-真实接口测试会使用本机登录凭证，并可能消耗额度：
+真实接口 smoke 会使用本机登录凭证，并可能消耗额度：
 
 ```bash
 gd-cli auth login

package/dist/bin/gd-cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { createProgram } from "../src/program.js";
+import { createProgram, parseProgram } from "../src/program.js";
 async function main() {
     const program = await createProgram();
-    await program.parseAsync(process.argv);
+    await parseProgram(program, process.argv);
 }
 main().catch((err) => {
     console.error(err.message);

package/dist/src/api/app-runner.d.ts

@@ -1,10 +1,7 @@
 import { HubClient } from "./hub-client.js";
 import type { TaskResult } from "./task-poller.js";
 interface RunOptions {
-    async?: boolean;
-    timeout?: number;
-    outputDir?: string;
-    concurrency?: number;
+    allowSensitivePath?: boolean;
     onStepStart?: (step: AppStepPublicRecord) => void;
     onStepComplete?: (step: AppStepPublicRecord, result?: TaskResult) => void;
 }

package/dist/src/api/app-runner.js

@@ -1,23 +1,5 @@
 import { DirectToolInvoker } from "./direct-tools.js";
 import { DirectApiError } from "./direct-client.js";
-/** 多步 App 含多次生图/对话，默认至少等待 10 分钟 */
-const APP_RUN_MIN_WAIT_SEC = 600;
-function resolveAppWaitTimeout(explicit, estimatedSeconds) {
-    if (explicit !== undefined && Number.isFinite(explicit) && explicit > 0) {
-        return Math.floor(explicit);
-    }
-    const est = Number(estimatedSeconds);
-    if (Number.isFinite(est) && est > APP_RUN_MIN_WAIT_SEC) {
-        return Math.ceil(est);
-    }
-    return APP_RUN_MIN_WAIT_SEC;
-}
-function resolveConcurrency(value) {
-    const numeric = Number(value);
-    if (!Number.isFinite(numeric) || numeric <= 0)
-        return 2;
-    return Math.max(1, Math.min(4, Math.floor(numeric)));
-}
 async function mapWithConcurrency(items, concurrency, worker) {
     let next = 0;
     const runners = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
@@ -170,15 +152,6 @@ export class AppRunner {
         void client;
     }
     async run(appId, params, options = {}) {
-        if (options.async) {
-            return {
-                task_id: `app-${appId}-${Date.now()}`,
-                status: "failed",
-                message: "本地 App workflow 暂不支持 --async，请去掉 --async 直接运行。",
-            };
-        }
-        void resolveAppWaitTimeout(options.timeout, undefined);
-        void options.outputDir;
         try {
             if (appId === "listing-gallery")
                 return await this.runListingGallery(params, options);
@@ -208,7 +181,7 @@ export class AppRunner {
             detail_image: "4:5",
             lifestyle_image: "4:5",
         });
-        const prepared = await this.prepareProduct(ctx, image, allowSensitivePath(params));
+        const prepared = await this.prepareProduct(ctx, image, options.allowSensitivePath === true);
         const title = await this.generateTitle(ctx, brief);
         const titleText = outputString(title, "text", false) || brief;
         const promptPlan = await this.optimizePrompt(ctx, "prompt_plan", "生成图库素材规划", `为电商 Listing 图库生成素材规划：${brief}。品类判断：${profile.label}。需要覆盖白底主图、单卖点证明图、材质/结构细节图、生活方式图；${copyPlanningGuidance(copyPlan)}每张图只回答一个购买问题，不生成假认证和不可验证参数。`, prepared.cutoutUrl, `Listing 图库素材规划：主图、卖点图、细节图、生活方式图。品类：${profile.label}。商品卖点：${brief}`);
@@ -310,7 +283,7 @@ export class AppRunner {
                     overlayCopy: overlayCopy.lifestyle_image,
                 }),
             },
-        ], options);
+        ]);
         return ctx.completed();
     }
     async runPdpAPlus(params, options) {
@@ -326,7 +299,7 @@ export class AppRunner {
             usage_module: "4:5",
             comparison_module: "1:1",
         });
-        const prepared = await this.prepareProduct(ctx, image, allowSensitivePath(params));
+        const prepared = await this.prepareProduct(ctx, image, options.allowSensitivePath === true);
         const title = await this.generateTitle(ctx, brief);
         const titleText = outputString(title, "text", false) || brief;
         const promptPlan = await this.optimizePrompt(ctx, "prompt_plan", "生成详情页模块规划", `为电商详情页/A+模块生成购买说服顺序：${brief}。品类判断：${profile.label}。模块包含首屏、痛点解决、结构/细节证明、真实使用场景、对比规格；${copyPlanningGuidance(copyPlan)}不编造参数和认证。`, prepared.cutoutUrl, `详情页模块规划：首屏、痛点、结构细节、使用场景、对比规格。品类：${profile.label}。商品信息：${brief}`);
@@ -451,7 +424,7 @@ export class AppRunner {
                     overlayCopy: overlayCopy.comparison_module,
                 }),
             },
-        ], options);
+        ]);
         return ctx.completed();
     }
     async runSocialSeedingPack(params, options) {
@@ -464,7 +437,7 @@ export class AppRunner {
             cover_image: "3:4",
             scene_image: "9:16",
         });
-        const prepared = await this.prepareProduct(ctx, image, allowSensitivePath(params));
+        const prepared = await this.prepareProduct(ctx, image, options.allowSensitivePath === true);
         const title = await this.generateTitle(ctx, brief);
         const titleText = outputString(title, "text", false) || brief;
         const xhsCaption = buildXhsCaption(titleText, brief);
@@ -534,7 +507,7 @@ export class AppRunner {
                     overlayCopy: overlayCopy.scene_image,
                 }),
             },
-        ], options);
+        ]);
         return ctx.completed();
     }
     async runCampaignKvPack(params, options) {
@@ -544,7 +517,7 @@ export class AppRunner {
         const ratios = parseRatioList(params.ratios ?? params.ratio, ["16:9", "1:1", "4:5"]);
         const profile = inferProductCategoryProfile(brief);
         const copyPlan = resolveCopyPlan(params, brief);
-        const prepared = await this.prepareProduct(ctx, image, allowSensitivePath(params));
+        const prepared = await this.prepareProduct(ctx, image, options.allowSensitivePath === true);
         const title = await this.generateTitle(ctx, brief);
         const titleText = outputString(title, "text", false) || brief;
         const promptPlan = await this.optimizePrompt(ctx, "prompt_plan", "生成 Campaign KV 主视觉提示词", `为新品 Campaign KV 生成${copyPlan.mode === "no-text" ? "无字主视觉" : "可直接投放主视觉"}提示词：${brief}。品类判断：${profile.label}。要求一个清晰记忆符号，可裁切到官网、社媒、电商活动和投放；${copyPlanningGuidance(copyPlan)}不改 logo、不生成假促销标。`, prepared.cutoutUrl, copyPlan.mode === "no-text"
@@ -595,11 +568,11 @@ export class AppRunner {
                     overlayCopy: String(overlayCopy[key] ?? ""),
                 }),
             };
-        }), options);
+        }));
         return ctx.completed();
     }
-    async generateImageJobs(ctx, jobs, options) {
-        await mapWithConcurrency(jobs, resolveConcurrency(options.concurrency), async (job) => {
+    async generateImageJobs(ctx, jobs) {
+        await mapWithConcurrency(jobs, 2, async (job) => {
             const result = await this.generateImage(ctx, job.key, job.stepName, job.prompt, job.image, job.ratio, job.model);
             ctx.outputs[job.key] = result.outputs;
             ctx.addAsset(job.label, job.key, result);
@@ -1159,11 +1132,6 @@ function optionalString(value) {
     const normalized = value.trim();
     return normalized ? normalized : undefined;
 }
-function allowSensitivePath(params) {
-    return (params.allow_sensitive_path === true ||
-        params.allowSensitivePath === true ||
-        params["allow-sensitive-path"] === true);
-}
 function outputString(result, key, required = true) {
     const outputs = result.outputs;
     const value = outputs?.[key];

package/dist/src/api/dam-client.d.ts

@@ -42,7 +42,6 @@ export interface DamSearchOptions {
     pageSize?: number;
     page?: number;
     cursor?: string;
-    raw?: boolean;
     allowEmptyKeyword?: boolean;
 }
 export interface DamSearchAsset {
@@ -74,12 +73,6 @@ export interface DamSearchResult {
     finish: boolean;
     next_cursor?: string;
     assets: DamSearchAsset[];
-    debug?: {
-        source: {
-            endpoint: string;
-            raw?: unknown;
-        };
-    };
 }
 interface DamCover {
     url?: string;

package/dist/src/api/dam-client.js

@@ -4,7 +4,6 @@ import { basename, extname, resolve } from "node:path";
 import OSS from "ali-oss";
 import sharp from "sharp";
 import { DirectApiClient, DirectApiError, unwrapEnvelope } from "./direct-client.js";
-import { isDebug, isVerbose } from "../utils/config.js";
 import { assertSafeUploadPath } from "../utils/sensitive-path.js";
 import { assertSafeHttpUrl } from "../utils/url-safety.js";
 import { redactSensitiveText } from "../utils/redact.js";
@@ -140,12 +139,9 @@ export class DamClient {
         try {
             const response = await this.client.post("/dam/asset/v2/search/simple", payload);
             return normalizeSearchResponse(response, {
-                endpoint: "/dam/asset/v2/search/simple",
                 query,
                 repositoryIds,
                 payload,
-                includeDebug: options.raw === true || isVerbose() || isDebug(),
-                includeRaw: options.raw === true,
             });
         }
         catch (error) {
@@ -153,12 +149,9 @@ export class DamClient {
                 throw error;
             const response = await this.client.post("/dam/asset/search", payload);
             return normalizeSearchResponse(response, {
-                endpoint: "/dam/asset/search",
                 query,
                 repositoryIds,
                 payload,
-                includeDebug: options.raw === true || isVerbose() || isDebug(),
-                includeRaw: options.raw === true,
             });
         }
     }
@@ -307,16 +300,6 @@ function normalizeSearchResponse(response, context) {
         finish,
         next_cursor: nextCursor,
         assets: rawItems.map(normalizeSearchAsset).filter((item) => item.asset_id),
-        ...(context.includeDebug
-            ? {
-                debug: {
-                    source: {
-                        endpoint: context.endpoint,
-                        ...(context.includeRaw ? { raw: response } : {}),
-                    },
-                },
-            }
-            : {}),
     };
 }
 function extractSearchContainer(value) {

package/dist/src/commands/auth.js

@@ -3,10 +3,7 @@ import { withErrorHandler } from "../middleware/error-handler.js";
 import { createAuthProvider } from "../core/auth/auth-provider.js";
 import { CredentialStoreV2 } from "../auth/credential-store-v2.js";
 import { resolveEndpoints, isVerbose, isDebug } from "../utils/config.js";
-import { getIO } from "../io.js";
 import { emitJson, wrapEnvelope } from "../core/output/envelope.js";
-import { setStaticHelp } from "../utils/static-help.js";
-import { resolveInvokeOutputFormat } from "../utils/list-output-format.js";
 import { setAuthRequirement } from "../middleware/auth.js";
 const loginAction = withErrorHandler(async (options) => {
     if (isVerbose() || isDebug()) {
@@ -15,22 +12,8 @@ const loginAction = withErrorHandler(async (options) => {
     }
     const provider = await createAuthProvider();
     const result = await provider.login({
-        orgId: options.org,
-        noBrowser: !!options.noBrowser,
-        scope: options.scope,
-        env: options.env,
+        noBrowser: options.browser === false,
     });
-    const io = getIO();
-    if (io.prefersJsonOutput()) {
-        emitJson(wrapEnvelope({
-            mode: provider.mode,
-            logged_in: true,
-            user: result.credentials.user,
-            org: result.org,
-            next_steps: result.org ? [] : ["gd-cli org switch"],
-        }, { command: "auth login" }));
-        return;
-    }
     console.log(chalk.green("\n✓ 授权成功，可以开始使用稿定能力进行创意生产\n"));
     if (!result.org) {
         console.log(chalk.yellow("  尚未选择当前组织，请执行 gd-cli org switch 后再调用 Creative / Workflows / DAM。"));
@@ -38,13 +21,12 @@ const loginAction = withErrorHandler(async (options) => {
 });
 const statusAction = withErrorHandler(async (_opts, command) => {
     const cmd = command;
-    const format = resolveInvokeOutputFormat(cmd);
-    const io = getIO();
+    const json = cmd.opts().json === true;
     const store = new CredentialStoreV2();
     const creds = store.read();
     const ep = resolveEndpoints();
     if (!creds) {
-        if (io.prefersJsonOutput(format)) {
+        if (json) {
             emitJson(wrapEnvelope({
                 logged_in: false,
                 environment: { active: ep.active_env },
@@ -57,7 +39,7 @@ const statusAction = withErrorHandler(async (_opts, command) => {
         return;
     }
     const payload = buildStatusPayload(creds, store);
-    if (io.prefersJsonOutput(format)) {
+    if (json) {
         emitJson(wrapEnvelope(payload, { command: "auth status" }));
         return;
     }
@@ -67,24 +49,15 @@ const logoutAction = withErrorHandler(async () => {
     const provider = await createAuthProvider();
     await provider.logout();
     new CredentialStoreV2().delete();
-    const io = getIO();
-    if (io.prefersJsonOutput()) {
-        emitJson(wrapEnvelope({ logged_out: true }, { command: "auth logout" }));
-        return;
-    }
     console.log(chalk.green("✓ 已取消授权，可以重新执行 gd-cli auth login 进行授权。\n"));
 });
 export function registerAuthCommand(program) {
     const auth = program
         .command("auth")
         .description("登录、退出、查看登录状态");
-    setStaticHelp(auth, AUTH_HELP);
     const login = auth
         .command("login")
         .description("浏览器/扫码授权登录")
-        .option("--org <org-id>", "登录后直接选择当前组织")
-        .option("--env <env>", "环境标识 cursor / claude / ci")
-        .option("--scope <scope>", "授权范围，逗号分隔")
         .option("--no-browser", "不自动打开浏览器")
         .action(loginAction);
     setAuthRequirement(login, "none");
@@ -96,19 +69,10 @@ export function registerAuthCommand(program) {
     const status = auth
         .command("status")
         .description("查看授权状态")
+        .option("--json", "输出机器可读 JSON")
         .action(statusAction);
     setAuthRequirement(status, "none");
 }
-const AUTH_HELP = `
-Usage: gd-cli auth [options] [command]
-
-登录、退出、查看登录状态
-
-Commands:
-  login             浏览器/扫码授权登录
-  logout            取消授权
-  status            查看授权状态
-`;
 function buildStatusPayload(creds, store) {
     const ep = resolveEndpoints();
     const credentialExpired = store.isAkExpired();