@gaoding/cli 0.0.0 → 1.0.0

package/dist/src/platform/url-safety.js

@@ -0,0 +1,100 @@
+import { isIP } from "node:net";
+export class UrlSafetyError extends Error {
+    constructor() {
+        super("URL 不可用于远程素材。");
+        this.name = "UrlSafetyError";
+    }
+}
+function fail() {
+    throw new UrlSafetyError();
+}
+function parseIpv4(hostname) {
+    if (isIP(hostname) !== 4)
+        return null;
+    return hostname.split(".").map(Number);
+}
+function isPrivateIpv4(parts) {
+    const first = parts[0] ?? -1;
+    const second = parts[1] ?? -1;
+    return first === 0
+        || first === 10
+        || first === 127
+        || (first === 169 && second === 254)
+        || (first === 172 && second >= 16 && second <= 31)
+        || (first === 192 && second === 168);
+}
+function expandIpv6(hostname) {
+    if (isIP(hostname) !== 6)
+        return null;
+    const [left = "", right = "", ...rest] = hostname.split("::");
+    if (rest.length > 0)
+        return null;
+    const leftParts = left === "" ? [] : left.split(":");
+    const rightParts = right === "" ? [] : right.split(":");
+    const missing = 8 - leftParts.length - rightParts.length;
+    if (!hostname.includes("::") && missing !== 0)
+        return null;
+    if (hostname.includes("::") && missing < 1)
+        return null;
+    const values = [
+        ...leftParts,
+        ...Array.from({ length: missing }, () => "0"),
+        ...rightParts
+    ].map((part) => Number.parseInt(part, 16));
+    return values.length === 8 && values.every((part) => Number.isInteger(part))
+        ? values
+        : null;
+}
+function isPrivateIpv6(parts) {
+    const first = parts[0] ?? -1;
+    const unspecified = parts.every((part) => part === 0);
+    const loopback = parts.slice(0, 7).every((part) => part === 0) && parts[7] === 1;
+    const uniqueLocal = (first & 0xfe00) === 0xfc00;
+    const linkLocal = (first & 0xffc0) === 0xfe80;
+    const mappedIpv4 = parts.slice(0, 5).every((part) => part === 0)
+        && parts[5] === 0xffff;
+    if (mappedIpv4) {
+        const high = parts[6] ?? 0;
+        const low = parts[7] ?? 0;
+        return isPrivateIpv4([
+            high >> 8,
+            high & 0xff,
+            low >> 8,
+            low & 0xff
+        ]);
+    }
+    return unspecified || loopback || uniqueLocal || linkLocal;
+}
+export function parseSafeRemoteAssetUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return fail();
+    }
+    if ((url.protocol !== "http:" && url.protocol !== "https:")
+        || url.username !== ""
+        || url.password !== "") {
+        return fail();
+    }
+    const hostname = url.hostname
+        .replace(/^\[|\]$/g, "")
+        .replace(/[.]+$/, "")
+        .toLowerCase();
+    if (hostname === "localhost"
+        || hostname.endsWith(".localhost")
+        || hostname.endsWith(".local")
+        || hostname === "metadata"
+        || hostname === "metadata.google.internal"
+        || hostname === "169.254.169.254") {
+        return fail();
+    }
+    const ipv4 = parseIpv4(hostname);
+    if (ipv4 !== null && isPrivateIpv4(ipv4))
+        return fail();
+    const ipv6 = expandIpv6(hostname);
+    if (ipv6 !== null && isPrivateIpv6(ipv6))
+        return fail();
+    return url;
+}

package/dist/src/telemetry/invocation.js

@@ -0,0 +1,156 @@
+const detailedStages = {
+    "auth.login": new Set(["authorize", "wait", "identity", "bind"]),
+    "org.switch": new Set(["list", "bind"]),
+    "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"])
+};
+export function createTelemetryInvocation(options) {
+    const traceId = options.traceIdFactory();
+    const startedAt = options.now();
+    let definition;
+    const context = {};
+    const stages = [];
+    return {
+        traceId,
+        get selected() {
+            return definition !== undefined;
+        },
+        traceparent() {
+            return `00-${traceId}-${options.spanIdFactory()}-${traceFlags(definition)}`;
+        },
+        select(nextDefinition) {
+            definition = nextDefinition;
+        },
+        annotate(annotation) {
+            if (annotation.account_id !== undefined)
+                context.account_id = annotation.account_id;
+            if (annotation.organization_id !== undefined) {
+                context.organization_id = annotation.organization_id;
+            }
+            if (annotation.tool_name !== undefined)
+                context.tool_name = annotation.tool_name;
+            if (annotation.model_id !== undefined)
+                context.model_id = annotation.model_id;
+            if (annotation.content_id !== undefined)
+                context.content_id = annotation.content_id;
+            if (annotation.task_id !== undefined)
+                context.task_id = annotation.task_id;
+            if (annotation.dify_task_id !== undefined) {
+                context.dify_task_id = annotation.dify_task_id;
+            }
+            if (annotation.parameters !== undefined) {
+                context.parameters = { ...annotation.parameters };
+            }
+        },
+        async stage(name, run) {
+            const stageStartedAt = options.now();
+            try {
+                const result = await run();
+                stages.push({
+                    name,
+                    durationMs: elapsed(options.now(), stageStartedAt),
+                    outcome: "success"
+                });
+                return result;
+            }
+            catch (error) {
+                const classification = options.classifyError(error);
+                stages.push({
+                    name,
+                    durationMs: elapsed(options.now(), stageStartedAt),
+                    outcome: classification.outcome,
+                    error,
+                    ...(classification.errorCode === undefined
+                        ? {}
+                        : { errorCode: classification.errorCode }),
+                    ...(classification.httpStatus === undefined
+                        ? {}
+                        : { httpStatus: classification.httpStatus })
+                });
+                throw error;
+            }
+        },
+        finish(completion) {
+            if (!definition)
+                return [];
+            const selectedDefinition = definition;
+            const mode = selectedDefinition.mode?.();
+            const allowedStages = detailedStages[stageKey(selectedDefinition.operation, mode)];
+            const stageEvents = allowedStages
+                ? stages
+                    .filter((stage) => allowedStages.has(stage.name))
+                    .map((stage) => ({
+                    schema_version: "2",
+                    event_name: "stage_finished",
+                    trace_id: traceId,
+                    operation: selectedDefinition.operation,
+                    stage: stage.name,
+                    outcome: stage.outcome,
+                    duration_ms: stage.durationMs,
+                    ...(stage.errorCode === undefined ? {} : { error_code: stage.errorCode }),
+                    ...(stage.httpStatus === undefined ? {} : { http_status: stage.httpStatus })
+                }))
+                : [];
+            const command = {
+                schema_version: "2",
+                event_name: "command_finished",
+                trace_id: traceId,
+                operation: selectedDefinition.operation,
+                ...(mode === undefined ? {} : { mode }),
+                outcome: completion.outcome,
+                duration_ms: elapsed(options.now(), startedAt),
+                cli_version: options.cliVersion,
+                os: options.runtime.os,
+                arch: options.runtime.arch,
+                node_major: options.runtime.nodeMajor,
+                ...(context.account_id === undefined ? {} : { account_id: context.account_id }),
+                ...(context.organization_id === undefined
+                    ? {}
+                    : { organization_id: context.organization_id }),
+                ...(context.tool_name === undefined ? {} : { tool_name: context.tool_name }),
+                ...(context.model_id === undefined ? {} : { model_id: context.model_id }),
+                ...(context.content_id === undefined ? {} : { content_id: context.content_id }),
+                ...(context.task_id === undefined ? {} : { task_id: context.task_id }),
+                ...(context.dify_task_id === undefined
+                    ? {}
+                    : { dify_task_id: context.dify_task_id }),
+                ...(context.parameters === undefined
+                    ? {}
+                    : { parameters: { ...context.parameters } }),
+                ...(completion.outcome === "failure"
+                    ? {
+                        error_code: completion.errorCode,
+                        error_message: completion.errorMessage,
+                        failure_stage: stages.find((stage) => stage.error === completion.error)?.name
+                            ?? "unknown",
+                        ...(completion.httpStatus === undefined
+                            ? {}
+                            : { http_status: completion.httpStatus }),
+                        ...(completion.remoteErrorCode === undefined
+                            ? {}
+                            : { remote_error_code: completion.remoteErrorCode }),
+                        ...(completion.remoteErrorBody === undefined
+                            ? {}
+                            : { remote_error_body: completion.remoteErrorBody })
+                    }
+                    : {})
+            };
+            return [...stageEvents, command];
+        }
+    };
+}
+function traceFlags(definition) {
+    if (definition === undefined)
+        return "00";
+    const paidExecution = (definition.operation === "agent.send"
+        || definition.operation === "tool.call") && definition.mode?.() === "execute";
+    return paidExecution ? "01" : "00";
+}
+function stageKey(operation, mode) {
+    return mode === undefined ? operation : `${operation}:${mode}`;
+}
+function elapsed(now, startedAt) {
+    return Math.max(0, now - startedAt);
+}

package/dist/src/telemetry/sls-sink.js

@@ -0,0 +1,31 @@
+const trackingUrl = new URL("https://gaoding-log-ai-gpu.cn-hangzhou.log.aliyuncs.com/logstores/gd-cli/track?APIVersion=0.6.0");
+const TIMEOUT_MS = 2_000;
+export function createSlsTelemetrySink(options) {
+    return {
+        async send(events) {
+            if (events.length === 0)
+                return;
+            try {
+                await options.fetch(trackingUrl, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ __logs__: events.map(wireEvent) }),
+                    redirect: "error",
+                    signal: AbortSignal.timeout(TIMEOUT_MS)
+                });
+            }
+            catch {
+                // Telemetry must never change command behavior.
+            }
+        }
+    };
+}
+function wireEvent(event) {
+    const wire = {};
+    for (const [key, value] of Object.entries(event)) {
+        if (value === undefined)
+            continue;
+        wire[key] = key === "parameters" ? JSON.stringify(value) : String(value);
+    }
+    return wire;
+}

package/package.json

@@ -1,16 +1,62 @@
 {
   "name": "@gaoding/cli",
-  "version": "0.0.0",
-  "description": "Placeholder package for the Gaoding CLI.",
-  "main": "index.js",
+  "version": "1.0.0",
+  "description": "Gaoding command-line interface for agents and people.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "gd-cli": "dist/bin/gd-cli.js"
+  },
   "files": [
-    "index.js"
+    "contracts",
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
-    "test": "node -e \"require('./index.js')\""
+    "contracts:build": "pnpm --filter @gaoding/gd-connector-contracts build",
+    "clean": "node -e \"for (const p of ['contracts', 'dist']) require('node:fs').rmSync(p, { recursive: true, force: true })\"",
+    "bundle:contracts": "node scripts/bundle-contracts.mjs",
+    "build": "pnpm contracts:build && pnpm clean && tsc -p tsconfig.build.json && pnpm bundle:contracts",
+    "test": "pnpm contracts:build && vitest run",
+    "typecheck": "pnpm contracts:build && tsc -p tsconfig.json",
+    "check": "pnpm contracts:build && vitest run && tsc -p tsconfig.json && pnpm clean && tsc -p tsconfig.build.json && pnpm bundle:contracts",
+    "prepack": "pnpm check",
+    "postinstall": "node -e \"const p='./dist/bin/postinstall.js'; if (require('node:fs').existsSync(p)) import(p)\""
   },
-  "publishConfig": {
-    "access": "public"
+  "dependencies": {
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "ali-oss": "6.23.0",
+    "commander": "14.0.3",
+    "open": "11.0.0",
+    "qrcode": "1.5.4",
+    "semver": "7.8.5",
+    "sharp": "0.35.3",
+    "ws": "8.21.1"
+  },
+  "devDependencies": {
+    "@gaoding/gd-connector-contracts": "workspace:*",
+    "@types/ali-oss": "6.23.3",
+    "@types/node": "24.13.3",
+    "@types/qrcode": "1.5.6",
+    "@types/semver": "7.7.1",
+    "@types/ws": "8.18.1",
+    "typescript": "7.0.2",
+    "vitest": "4.1.10"
   },
-  "license": "UNLICENSED"
+  "gaodingRelease": {
+    "sourceCommit": "10a20a2c28b2eb959b8b62dbe692c6a54ec94b3f",
+    "pipelineId": "168684",
+    "pipelineUrl": "https://git.intra.gaoding.com/gtt/gaoding-cli/-/pipelines/168684"
+  }
 }

package/skills/gd-cli/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: gd-cli
+description: Use when creating images, videos or text with GD CLI, operating the focused Gaoding editor, or managing Gaoding DAM assets.
+---
+
+# GD CLI
+
+按用户目标只读取对应参考：
+
+- 按业务意图选择 Agent / Tool 创作路由、发现 Model 并生成图片、视频或文本：[创作](references/creation.md)
+- 操作当前 AI+ Editor 作品：[编辑器](references/editor.md)
+- 发现资源库、文件夹与标签，查询、上传、下载或单条目管理 DAM 资源：[素材管理](references/dam.md)
+- 登录或选择组织：[登录与组织](references/auth-org.md)
+- 处理输出、警告、失败或中断：[错误处理](references/errors.md)
+- 更新 CLI 与随包 Agent Skill：[更新](references/update.md)

package/skills/gd-cli/references/auth-org.md

@@ -0,0 +1,9 @@
+# 登录与组织
+
+1. 用 `gd-cli auth status` 检查登录状态；需要机器读取时使用 `--json`。
+2. 未登录时执行 `gd-cli auth login`，按终端提示在浏览器完成授权；无法自动打开浏览器时使用 `--no-browser`。
+3. 用 `gd-cli org list` 查看当前账号可用的组织，用 `gd-cli org current` 查看当前选择。
+4. 让用户从真实列表中选择，再执行 `gd-cli org switch --org <org-id>`；不要猜组织 ID。
+5. 用户要求退出或登录状态失效时执行 `gd-cli auth logout`；状态失效后重新登录。
+
+不要向用户索要或回显 Bearer Token、Cookie、AK、SK 或签名。组织不可用时先切换组织；仍无法恢复时退出后重新登录。

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

@@ -0,0 +1,115 @@
+# 创作
+
+## Creation Route
+
+先判断 Creation Route，再选择或校验 Model。Model 和参数不决定 Agent 或 Tool 路由；两条路由都支持指定 Model 及其参数，`model list` 和 `model get` 是共享的实时发现能力。
+
+- Agent：用户要的是业务交付物，或过程需要澄清、规划、多步骤、多产物或继续已有创作。下列十类业务意图通常优先走 Agent；它们只帮助选择 Creation Route，具体 Business Skill 由服务端 Agent 选择。
+- Tool：任务是一个无需业务编排的原子单次图片、视频或文本调用，或用户明确要求直接调用 Tool。
+
+业务意图参考（语义匹配，不是只能逐字命中）：
+
+| 业务意图 | 常见说法 | 素材与边界 |
+| --- | --- | --- |
+| 电商主图套图 | 主图、主图套图、一套主图、主图设计、商品图 | 通常带商品图；区分场景图、海报、详情页、改图、包装设计和多角度图 |
+| 电商详情页 | 详情页、电商详情、宝贝详情、产品详情、长图、卖点页、参数页、功能介绍、对比说明、购买理由 | 通常带商品图；出现“详情”类词时优先按电商详情页判断，不按主图套图处理 |
+| 商品精修 | 精修、修一下、翻新、白底图、纯白背景、修复使用痕迹 | 必须提供商品实物图；加文字、去水印、抠图、局部编辑、海报、套版和仿图不按商品精修判断 |
+| 电商模特 | 模特、试穿、上身、穿戴、佩戴、换模特、换姿势、换背景 | 商品图可选；没有商品图时可以生成纯模特 |
+| 商品场景图 | 生成场景、换场景、换个背景、整合到一张图+背景 | 必须提供商品实物图；人像、风景和设计稿不算商品图，带卖点文字的主图不按商品场景图判断 |
+| 主题照 | 主题照、写真、风格人像 | 人像图可选 |
+| 形象照 | 形象照、职业照 | 人像图可选 |
+| 证件照 | 证件照、报名照、头像照，包括换底色和改尺寸 | 人像图可选 |
+| 电商图片提示词 | 写电商图片提示词、产品主图提示词 | 服务端按当前组织的 Business Skill 可用性处理 |
+| 电商视频提示词 | 电商视频提示词、带货视频、产品宣传视频 | 服务端按当前组织的 Business Skill 可用性处理 |
+
+这些参考不在 CLI 选择具体 Business Skill，也不代替服务端实时可用性。业务意图成立但缺少必需素材时，仍使用 Agent 并请用户提供素材；不要因此降级为 Tool。指定 Model、分辨率、比例、时长等参数也不改变路由。
+
+状态映射：原“商品白底图”Business Skill 已下线，白底图或纯白背景需求按商品精修意图走 Agent；原“小红书人像封面”Business Skill 已下线，相关种草人像封面需求走 Agent 兜底。状态只解释路由，不表示 CLI 指定了服务端 Skill。
+
+典型判断：
+
+- “指定 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
+```
+
+将用户要求放在 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 创作
+
+按顺序执行：
+
+```bash
+gd-cli tool list
+gd-cli model list --tool <tool>
+gd-cli model get <model>
+gd-cli tool call <tool> --input request.json
+```
+
+`tool list` 给出可用 Tool；`model list` 和 `model get` 给出当前可用 Model、说明、费用、预估耗时和结构化参数。`model get` 的 `parameters` 是所选 Model 的实际调用元数据：遵循 `required`、`type`、`description`，SELECT 参数使用 `options[].value`，required 参数带 `default` 时在用户未指定时显式传入默认值。`usageDescription` 描述跨字段规则，例如视频 mode 对首尾帧或素材字段的要求；这类组合不能只从单个字段推断。不要把列表值固化在提示或脚本中。
+
+按所选 Model detail 构造 JSON：提供全部 required 字段；SELECT 参数使用 `options[].value`；required 字段带 default 且用户未指定时，在输入中显式使用该 default。存在 width、height、resolution 等专用字段时，将用户要求写入对应结构化参数，不要只写在 prompt 中。`tool call <tool> --schema` 返回整个 Tool 下所有 Model 的参数并集，只用于 Tool 级发现；选定 Model 后以 `model get` 的参数和 `usageDescription` 为准。
+
+务必将 `model get <model>` 返回的 `model` 原样放在请求 JSON 的顶层 `model` 字段（即运行时的 `arguments.model`），与所选 Model 的参数字段并列；不要只复制 `parameters`。例如：
+
+```json
+{
+  "model": "<model>",
+  "prompt": "<required prompt>",
+  "<parameter>": "<value>"
+}
+```
+
+成功结果包含 `content` 和 `usage`。`content` 是文本或资源链接；`usage` 包含所选模型及模型目录公布的稿豆价格区间，不表示实际扣费。
+
+## 本地媒体
+
+Agent 将本地媒体写成独立 `file://` URL Part；Tool 按所选 Model detail 写入对应媒体参数。CLI 会在内部通过 DAM 完成临时上传并把公网 URL 传给创作服务；不要自行伪造 URL，也不要读取用户未明确授权的路径。

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

@@ -0,0 +1,52 @@
+# DAM 素材管理
+
+## 先发现，再操作
+
+任何资源库范围内的查询或写入都先运行：
+
+```bash
+gd-cli org current
+gd-cli dam repository list --json
+```
+
+只使用返回的 `repositories[].repository_id`。团队资源库的 `type` 为 `team`，企业资源库的 `type` 为 `enterprise`；不要使用名称、前端 URL、团队实体 ID 或历史值猜 ID。资源库不做 switch，`org switch` 只切换组织。
+
+需要文件夹或标签 ID 时继续发现：
+
+```bash
+gd-cli dam folder list --repository-id <id> --json
+gd-cli dam tag list --repository-id <id> --json
+```
+
+文件夹可用 `--parent-id`、`--query`、`--page` 和 `--page-size`；标签可用 `--query`。根文件夹 ID 为 `0`，涉及目标位置时必须显式传 `--target-folder-id 0`，不要把缺省值理解为根目录。
+
+## 查询与下载
+
+```bash
+gd-cli dam list --repository-id <id> --json
+gd-cli dam search <query> --repository-id <id> --json
+gd-cli dam get <asset-id> --json
+gd-cli dam download <asset-id> --repository-id <id> --output-dir ./downloads --json
+```
+
+跨资源库查询只在用户明确要求时使用 `--all-repositories`。列表或搜索按需增加文件夹、类型、格式、标签、数量和游标筛选。下载只支持一个素材，不支持文件夹下载，也不会覆盖已存在的同名文件。
+
+## 单条目写入
+
+```bash
+gd-cli dam upload ./asset.png --repository-id <id> --folder-id <folder-id> --tag-ids <tag-id> --json
+gd-cli dam rename <entry-id> --kind asset --title <new-title> --repository-id <id> --json
+gd-cli dam copy <entry-id> --kind asset --repository-id <source-id> --target-repository-id <target-id> --target-folder-id <folder-id> --json
+gd-cli dam move <entry-id> --kind asset --repository-id <source-id> --target-repository-id <target-id> --target-folder-id <folder-id> --json
+gd-cli dam delete <asset-id> --repository-id <id>
+```
+
+- `rename`、`move`、`copy` 的 `--kind` 只能是 `asset` 或 `folder`。
+- 一次只处理一个素材或文件夹；不拆分或模拟批量操作。
+- 上传受保护路径时，只有用户明确允许才加 `--allow-sensitive-path`；需要等待分析完成时加 `--wait-analysis`。
+- 复制结果可能没有 `copied_entry_id`，这不表示失败；查询目标文件夹或目标资源库发现新副本，不要猜测新 ID，也不要再次提交 copy。
+- 移动、复制或重命名若返回“已提交但未确认”，先查询目标位置并报告诊断 ID，不要立即重复提交。
+- 删除默认移入回收站；只有用户明确要求永久删除时才加 `--permanent`。
+- 回收站列表和恢复暂不可用，不要尝试不存在的 `dam recycle` 命令。
+
+写操作前确认资源库、条目 ID、类型和目标位置。优先从本轮 JSON 输出取得 ID，不从本地登录状态或旧输出替用户猜测。