gaoding-cli 1.0.0-alpha.15 → 1.0.0-alpha.17

package/README.md

@@ -33,6 +33,8 @@ gd-cli model get <model>
 
 选定 Model 后，以 `model get` 返回的 `parameters` 与 `usageDescription` 构造实际输入；`tool call --schema` 只给出整个 Tool 的参数并集。运行 `gd-cli --help` 查看当前命令；运行任一命令的 `--help` 查看参数。`gd-cli update` 固定检查 npm `latest`，支持更新 npm、pnpm 全局安装并同步 Agent Skill。
 
+发布切换必须先完成精确版本的安装验收，再执行仓库中的 `scripts/promote-latest.mjs`；不要直接用未校验的 `npm dist-tag add` 移动 `latest`。
+
 ## License
 
 MIT

package/contracts/operations/agent.send/input.schema.json

@@ -60,7 +60,7 @@
             "parts": {
               "type": "array",
               "contains": {
-                "$ref": "#/$defs/CreativeParametersPart"
+                "$ref": "#/$defs/GenerationConstraintsPart"
               },
               "minContains": 0,
               "maxContains": 1
@@ -145,7 +145,7 @@
           "$ref": "#/$defs/InputAssetPart"
         },
         {
-          "$ref": "#/$defs/CreativeParametersPart"
+          "$ref": "#/$defs/GenerationConstraintsPart"
         },
         {
           "$ref": "#/$defs/QuestionAnswerPart"
@@ -211,7 +211,7 @@
         }
       }
     },
-    "CreativeParametersPart": {
+    "GenerationConstraintsPart": {
       "type": "object",
       "additionalProperties": false,
       "required": [
@@ -222,24 +222,19 @@
           "type": "object",
           "additionalProperties": false,
           "minProperties": 1,
-          "description": "本次创作的可选参数。",
+          "description": "本次创作指定的模型与动态参数；它们不决定 Agent 或 Tool 路由。",
           "properties": {
-            "ratio": {
+            "model": {
               "type": "string",
               "minLength": 1,
               "pattern": ".*\\S.*",
-              "description": "输出画面比例，例如 16:9。"
+              "description": "可选创作模型机器标识；指定时由 CLI 根据实时 Model Catalog 校验。"
             },
-            "resolution": {
-              "type": "string",
-              "minLength": 1,
-              "pattern": ".*\\S.*",
-              "description": "输出分辨率。"
-            },
-            "durationSeconds": {
-              "type": "integer",
-              "minimum": 1,
-              "description": "视频或音频时长，单位为秒。"
+            "arguments": {
+              "type": "object",
+              "minProperties": 1,
+              "description": "按模型公开字段传递的动态控制参数；素材使用独立 InputAssetPart。",
+              "additionalProperties": true
             }
           }
         }

package/dist/src/bootstrap/create-runtime.js

@@ -144,6 +144,7 @@ export function createProductionRuntime(options = {}) {
     });
     const browser = createBrowserOpener();
     const validators = createContractValidators();
+    const modelCatalog = createMnsCatalogAdapter({ transport: mnsTransport });
     const damApi = createDamApiAdapter({ transport: damTransport });
     const dam = createDamUseCases({
         api: damApi,
@@ -165,16 +166,18 @@ export function createProductionRuntime(options = {}) {
         telemetry
     });
     const agent = createAgentUseCases({
+        catalog: modelCatalog,
         uploader: transientUploader,
         completion: createCreativeAgentAdapter({
             transport: agentTransport,
             idFactory: randomUUID,
             telemetry
         }),
+        warn: (message) => { presenter.warning(message); },
         telemetry
     });
     const tool = createToolUseCases({
-        catalog: createMnsCatalogAdapter({ transport: mnsTransport }),
+        catalog: modelCatalog,
         execution: createToolApiAdapter({ transport: toolTransport, telemetry }),
         uploader: transientUploader,
         warn: (message) => { presenter.warning(message); },

package/dist/src/features/agent/creative-protocol.js

@@ -3,11 +3,13 @@ export function buildCreativeRequest(message, ids) {
     const prompt = [];
     const textParts = [];
     const attachments = [];
-    const parameters = {};
+    const parameters = Object.create(null);
     const answerValues = [];
     const answeredQuestions = [];
     let questionMessageId;
     let hasAnswers = false;
+    let hasGeneration = false;
+    let model;
     for (const part of message.parts) {
         if (part.kind === "text") {
             textParts.push(part.text);
@@ -15,12 +17,6 @@ export function buildCreativeRequest(message, ids) {
             continue;
         }
         if (part.kind === "asset") {
-            if (part.role === "first_frame" || part.role === "last_frame") {
-                prompt.push({
-                    type: "text",
-                    content: part.role === "first_frame" ? "首帧" : "尾帧"
-                });
-            }
             prompt.push({
                 type: "media",
                 url: part.asset.url,
@@ -34,14 +30,10 @@ export function buildCreativeRequest(message, ids) {
             });
             continue;
         }
-        if (part.kind === "parameters") {
-            if (part.data.ratio !== undefined)
-                parameters.ratio = part.data.ratio;
-            if (part.data.resolution !== undefined)
-                parameters.resolution = part.data.resolution;
-            if (part.data.durationSeconds !== undefined) {
-                parameters.duration = String(part.data.durationSeconds);
-            }
+        if (part.kind === "generation") {
+            hasGeneration = true;
+            model = part.data.model ?? model;
+            Object.assign(parameters, part.data.arguments);
             continue;
         }
         hasAnswers = true;
@@ -52,25 +44,28 @@ export function buildCreativeRequest(message, ids) {
             answeredQuestions.push({ question: answer.question, answers: values });
         }
     }
-    const hasParameters = Object.keys(parameters).length > 0;
+    const generationFields = {
+        ...(model === undefined ? {} : { scene_code: model }),
+        ...(hasGeneration ? { parameters } : {})
+    };
     let content;
     if (hasAnswers) {
         content = {
             type: "user",
             text: textParts.join("\n"),
             prompt: prompt.length > 0 ? prompt : [{ type: "text", content: "" }],
-            ...(hasParameters ? { parameters } : {}),
+            ...generationFields,
             answer: { answers: answerValues }
         };
     }
-    else if (prompt.length === 1 && prompt[0]?.type === "text" && !hasParameters) {
+    else if (prompt.length === 1 && prompt[0]?.type === "text" && !hasGeneration) {
         content = { type: "plain", text: prompt[0].content };
     }
     else {
         content = {
             type: "plain",
             prompt,
-            ...(hasParameters ? { parameters } : {})
+            ...generationFields
         };
     }
     const extra = {};

package/dist/src/features/agent/use-cases.js

@@ -1,3 +1,5 @@
+import { findModel, ToolInputError } from "../tool/catalog.js";
+import { modelControlArgumentsAreValid } from "../tool/dynamic-schema.js";
 import { parseSafeRemoteAssetUrl, UrlSafetyError } from "../../platform/url-safety.js";
 export class AgentInputError extends Error {
     constructor() {
@@ -37,6 +39,33 @@ export function createAgentUseCases(dependencies) {
         async send({ input, access, signal }) {
             signal.throwIfAborted();
             const prepared = [];
+            let generation;
+            for (const part of input.message.parts) {
+                if ("data" in part && !("questionMessageId" in part.data)) {
+                    generation = part.data;
+                    break;
+                }
+            }
+            if (generation?.model !== undefined) {
+                dependencies.telemetry.annotate({ model_id: generation.model });
+                const catalog = await dependencies.telemetry.stage("catalog", () => (dependencies.catalog.load({ access, signal })));
+                signal.throwIfAborted();
+                for (const warning of catalog.warnings)
+                    dependencies.warn(warning);
+                await dependencies.telemetry.stage("input", async () => {
+                    let model;
+                    try {
+                        model = findModel(catalog, generation.model);
+                    }
+                    catch (error) {
+                        if (error instanceof ToolInputError)
+                            throw new AgentInputError();
+                        throw error;
+                    }
+                    if (!modelControlArgumentsAreValid(model, generation.arguments ?? {}))
+                        throw new AgentInputError();
+                });
+            }
             const prepare = async () => {
                 for (const part of input.message.parts) {
                     signal.throwIfAborted();
@@ -92,13 +121,12 @@ export function createAgentUseCases(dependencies) {
                         continue;
                     }
                     prepared.push({
-                        kind: "parameters",
+                        kind: "generation",
                         data: {
-                            ...(part.data.ratio === undefined ? {} : { ratio: part.data.ratio }),
-                            ...(part.data.resolution === undefined ? {} : { resolution: part.data.resolution }),
-                            ...(part.data.durationSeconds === undefined
+                            ...(part.data.model === undefined ? {} : { model: part.data.model }),
+                            ...(part.data.arguments === undefined
                                 ? {}
-                                : { durationSeconds: part.data.durationSeconds })
+                                : { arguments: { ...part.data.arguments } })
                         }
                     });
                 }

package/dist/src/features/tool/dynamic-schema.js

@@ -98,9 +98,31 @@ addFormats(ajv);
 function validator(model) {
     return ajv.compile(buildModelArgumentsSchema(model));
 }
+function controlArgumentsValidator(model) {
+    const properties = {};
+    for (const parameter of model.parameters) {
+        if (parameter.name === "prompt"
+            || parameter.type === "uri"
+            || parameter.type === "uri[]")
+            continue;
+        properties[parameter.name] = parameterSchema(parameter);
+    }
+    return ajv.compile({
+        type: "object",
+        properties,
+        required: [],
+        additionalProperties: false
+    });
+}
 export function assertModelArguments(model, value) {
     if (typeof value !== "object" || value === null
         || !validator(model)(value)) {
         throw new ToolInputError();
     }
 }
+export function modelControlArgumentsAreValid(model, value) {
+    return typeof value === "object"
+        && value !== null
+        && !Array.isArray(value)
+        && controlArgumentsValidator(model)(value);
+}

package/dist/src/features/tool/tool-api-adapter.js

@@ -47,6 +47,21 @@ function parseIntent(value) {
         arguments: parseRecord(nonBlank(value.arguments))
     };
 }
+function isEmptyOptionalMedia(value) {
+    return value === undefined
+        || value === null
+        || value === ""
+        || (Array.isArray(value) && value.length === 0)
+        || (typeof value === "string" && value.trim() === "[]");
+}
+function withoutEmptyOptionalMedia(value, optionalMediaParameters) {
+    const normalized = { ...value };
+    for (const name of optionalMediaParameters) {
+        if (isEmptyOptionalMedia(normalized[name]))
+            delete normalized[name];
+    }
+    return normalized;
+}
 function submittedTask(value) {
     if (!isRecord(value) || !isRecord(value.result))
         return protocolFailure(value);
@@ -143,6 +158,17 @@ function optionalInnerDifyTaskId(value) {
         return undefined;
     }
 }
+function isJsonRpcError(value) {
+    if (value.jsonrpc !== "2.0"
+        || Object.prototype.hasOwnProperty.call(value, "result")
+        || !isRecord(value.error)) {
+        return false;
+    }
+    return typeof value.error.code === "number"
+        && Number.isInteger(value.error.code)
+        && typeof value.error.message === "string"
+        && value.error.message.trim() !== "";
+}
 function pollResult(value, taskId) {
     if (!Array.isArray(value))
         return protocolFailure(value);
@@ -175,6 +201,11 @@ function pollResult(value, taskId) {
         && (typeof difyTaskId !== "string" || difyTaskId.trim() === "")) {
         return protocolFailure(inner);
     }
+    if (Object.prototype.hasOwnProperty.call(inner, "error")) {
+        return isJsonRpcError(inner)
+            ? failedPoll(new ToolTaskFailedError(remoteErrorEvidence(inner)), difyTaskId)
+            : failedPoll(new RemoteProtocolError(remoteErrorEvidence(inner)), difyTaskId);
+    }
     if (!isRecord(inner.result)) {
         return failedPoll(new RemoteProtocolError(remoteErrorEvidence(inner)), difyTaskId);
     }
@@ -240,17 +271,25 @@ export function createToolApiAdapter(dependencies) {
         async execute({ invocation, access, signal }) {
             signal.throwIfAborted();
             const managedContentId = contentId(createContentId());
-            const intent = await dependencies.telemetry.stage("intent", async () => parseIntent(await safePost(dependencies.transport, {
-                path: "/ai-agent/v1/tool-intent",
-                body: {
-                    prompt: invocation.prompt,
-                    scene_code: invocation.model,
-                    parameters: invocation.parameters
-                },
-                credential: access.credential,
-                organizationId: access.organizationId,
-                signal
-            })));
+            const resolved = invocation.kind === "direct"
+                ? { name: invocation.name, arguments: invocation.arguments }
+                : await dependencies.telemetry.stage("intent", async () => {
+                    const intent = parseIntent(await safePost(dependencies.transport, {
+                        path: "/ai-agent/v1/tool-intent",
+                        body: {
+                            prompt: invocation.prompt,
+                            scene_code: invocation.model,
+                            parameters: invocation.parameters
+                        },
+                        credential: access.credential,
+                        organizationId: access.organizationId,
+                        signal
+                    }));
+                    return {
+                        ...intent,
+                        arguments: withoutEmptyOptionalMedia(intent.arguments, invocation.optionalMediaParameters)
+                    };
+                });
             signal.throwIfAborted();
             const taskId = await dependencies.telemetry.stage("submit", async () => {
                 dependencies.telemetry.annotate({ content_id: managedContentId });
@@ -261,8 +300,8 @@ export function createToolApiAdapter(dependencies) {
                         id: 0,
                         method: "tools/call",
                         params: {
-                            name: intent.name,
-                            arguments: { ...intent.arguments, content_id: managedContentId }
+                            name: resolved.name,
+                            arguments: { ...resolved.arguments, content_id: managedContentId }
                         }
                     },
                     credential: access.credential,

package/dist/src/features/tool/use-cases.js

@@ -86,6 +86,7 @@ export function createToolUseCases(dependencies) {
             });
             const prompt = [];
             const requestParameters = {};
+            const directArguments = {};
             const prepare = async () => {
                 for (const parameter of model.parameters) {
                     signal.throwIfAborted();
@@ -95,14 +96,17 @@ export function createToolUseCases(dependencies) {
                     if (parameter.type === "string") {
                         if (parameter.name === "prompt") {
                             prompt.push({ type: "text", content: value });
+                            directArguments[parameter.name] = value;
                         }
                         else {
                             requestParameters[parameter.name] = value;
+                            directArguments[parameter.name] = value;
                         }
                         continue;
                     }
                     if (parameter.type === "number") {
                         requestParameters[parameter.name] = value;
+                        directArguments[parameter.name] = value;
                         continue;
                     }
                     const values = parameter.type === "uri[]" ? value : [value];
@@ -138,8 +142,26 @@ export function createToolUseCases(dependencies) {
                 await prepare();
             }
             signal.throwIfAborted();
+            const requiresIntent = prompt.some((item) => item.type === "media")
+                || Object.values(requestParameters).some((value) => value === "");
+            const invocation = requiresIntent
+                ? {
+                    kind: "intent",
+                    model: model.model,
+                    prompt,
+                    parameters: requestParameters,
+                    optionalMediaParameters: model.parameters
+                        .filter((parameter) => ((parameter.type === "uri" || parameter.type === "uri[]")
+                        && !parameter.required))
+                        .map((parameter) => parameter.name)
+                }
+                : {
+                    kind: "direct",
+                    name: model.model,
+                    arguments: directArguments
+                };
             const content = await dependencies.execution.execute({
-                invocation: { model: model.model, prompt, parameters: requestParameters },
+                invocation,
                 access,
                 signal
             });

package/dist/src/platform/remote-error-evidence.js

@@ -3,7 +3,7 @@ const maximumLength = 8_192;
 const truncationMarker = "[TRUNCATED]";
 export function remoteErrorEvidence(value) {
     const normalized = parseJson(value);
-    const remoteCode = topLevelCode(normalized);
+    const remoteCode = topLevelCode(normalized) ?? jsonRpcErrorCode(normalized);
     const sanitized = sanitize(normalized);
     if (sanitized === undefined) {
         return remoteCode === undefined ? {} : { remoteCode };
@@ -31,7 +31,21 @@ function topLevelCode(value) {
         return undefined;
     if (!Object.prototype.hasOwnProperty.call(value, "code"))
         return undefined;
-    const code = value.code;
+    return normalizeCode(value.code);
+}
+function jsonRpcErrorCode(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (record.jsonrpc !== "2.0"
+        || record.error === null
+        || typeof record.error !== "object"
+        || Array.isArray(record.error)) {
+        return undefined;
+    }
+    return normalizeCode(record.error.code);
+}
+function normalizeCode(code) {
     if (typeof code === "string")
         return redactRemoteText(code);
     return typeof code === "number" ? String(code) : undefined;

package/dist/src/telemetry/invocation.js

@@ -1,7 +1,7 @@
 const detailedStages = {
     "auth.login": new Set(["authorize", "wait", "identity", "bind"]),
     "org.switch": new Set(["list", "bind"]),
-    "agent.send:execute": new Set(["upload", "execute", "result"]),
+    "agent.send:execute": new Set(["catalog", "upload", "execute", "result"]),
     "tool.call:execute": new Set(["catalog", "upload", "intent", "submit", "wait"]),
     "dam.upload": new Set(["inspect", "repository", "prepare", "upload", "persist", "wait"]),
     update: new Set(["registry", "install", "sync", "verify"])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gaoding-cli",
-  "version": "1.0.0-alpha.15",
+  "version": "1.0.0-alpha.17",
   "description": "Gaoding command-line interface for agents and people.",
   "type": "module",
   "license": "MIT",

package/skills/gd-cli/SKILL.md

@@ -7,7 +7,7 @@ description: Use when creating images, videos or text with GD CLI, operating the
 
 按用户目标只读取对应参考：
 
-- 开放式创作、工具发现与模型调用：[创作](references/creation.md)
+- 选择创作路由、发现 Model 并生成图片、视频或文本：[创作](references/creation.md)
 - 操作当前 AI+ Editor 作品：[编辑器](references/editor.md)
 - 查询、上传或删除 DAM 素材：[素材管理](references/dam.md)
 - 登录或选择组织：[登录与组织](references/auth-org.md)

package/skills/gd-cli/references/creation.md

@@ -1,21 +1,68 @@
 # 创作
 
-## 选择入口
+## Creation Route
 
-- 目标开放、需要稿定 Agent 完成创作时，使用 `gd-cli agent send`。
-- 已知要调用具体图片、视频或文本能力时，依次发现 Tool、选择 Model、读取 Model detail，再调用 Tool。
-- 不猜 Tool 名、Model 名或参数；以当前命令输出为准。
+先判断 Creation Route，再选择或校验 Model。Model 和参数不决定 Agent 或 Tool 路由；两条路由都支持指定 Model 及其参数，`model list` 和 `model get` 是共享的实时发现能力。
+
+- Agent：用户要的是业务交付物，或过程需要澄清、规划、多步骤、多产物或继续已有创作。具体 Business Skill 由服务端 Agent 选择，CLI 不猜测或复制服务端匹配规则。
+- Tool：任务是一个无需业务编排的原子单次图片、视频或文本调用，或用户明确要求直接调用 Tool。
+
+典型判断：
+
+- “指定 Model 的电商主图套图”仍使用 Agent，因为目标是业务交付物且可能需要多产物编排。
+- “规划三种风格，再分别生成图片”使用 Agent，因为它包含规划和多步骤。
+- “指定 Model 生成一只猫”使用 Tool，因为它只是原子单次调用，而不是因为指定了 Model。
+- 用户明确要求直接调用某个 Tool 时，使用 Tool。
+
+不猜 Tool 名、Model 名或参数；以当前命令输出为准。用户询问推荐 Model、Model 能力、参数或稿豆价格时，先用 `model list` 筛选，再用 `model get` 核对实时详情。
 
 ## Agent 创作
 
-先读取输入规范，再提交同一份结构化对象：
+先读取输入规范。需要指定 Model 时，也先读取实时 Model detail：
 
 ```bash
 gd-cli agent send --schema
+gd-cli model list --tool <tool>
+gd-cli model get <model>
 gd-cli agent send --input request.json
 ```
 
-也可用 `--input -` 从 stdin 读取 JSON。成功结果包含 `message` 和本轮实际稿豆消耗 `usage`；将文本、资源与实际消耗交付给用户。
+将用户要求放在 Text Part。指定 Model 和动态参数时，只增加一个 Generation Constraints Part；`model` 使用 Model 机器标识，`arguments` 的字段和值取自 `model get`，并如实保留用户指定值：
+
+```json
+{
+  "message": {
+    "parts": [
+      { "text": "<用户要求>" },
+      {
+        "data": {
+          "model": "<model>",
+          "arguments": {
+            "resolution": "2K"
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+`arguments` 可以在不指定 `model` 时单独提交，由服务端 Agent 选择 Model。指定 `model` 时，CLI 会按实时 Model detail 校验已提供参数；不要为了 Agent 调用补齐 Tool 的全部 required 字段。Prompt 使用 Text Part，素材使用独立 URL Part，不放入 `arguments`。素材保持消息 Part 的输入顺序；`metadata.role` 可标记 `reference`、`first_frame` 或 `last_frame`，不注入“首帧”或“尾帧”文本。例如：
+
+```json
+{
+  "message": {
+    "parts": [
+      { "text": "生成一段转场视频" },
+      { "url": "file:///absolute/first.png", "metadata": { "role": "first_frame" } },
+      { "url": "file:///absolute/last.png", "metadata": { "role": "last_frame" } },
+      { "data": { "model": "<model>", "arguments": { "mode": "<value>" } } }
+    ]
+  }
+}
+```
+
+也可用 `--input -` 从 stdin 读取 JSON。成功结果包含 `message` 和本轮实际稿豆消耗 `usage`；将最终文本、资源、服务端续作标识和实际消耗交付给用户。
 
 ## Tool 创作
 
@@ -46,4 +93,4 @@ gd-cli tool call <tool> --input request.json
 
 ## 本地媒体
 
-按所选 Model detail 在输入中提交本地媒体引用。CLI 会在内部通过 DAM 完成临时上传并把公网 URL 传给创作服务；不要自行伪造 URL，也不要读取用户未明确授权的路径。
+Agent 将本地媒体写成独立 `file://` URL Part；Tool 按所选 Model detail 写入对应媒体参数。CLI 会在内部通过 DAM 完成临时上传并把公网 URL 传给创作服务；不要自行伪造 URL，也不要读取用户未明确授权的路径。