gaoding-cli 1.0.0-alpha.5

package/dist/src/utils/write-app-deliverables.js

@@ -0,0 +1,386 @@
+import { createWriteStream } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { ZipArchive } from "archiver";
+import { createUniqueOutputDir, resolveSafeOutputDir } from "./output-path.js";
+import { redactSensitiveText } from "./redact.js";
+import { assertSafeHttpUrl } from "./url-safety.js";
+function pad2(n) {
+    return n < 10 ? `0${n}` : String(n);
+}
+function nowStamp() {
+    const d = new Date();
+    return `${d.getFullYear()}${pad2(d.getMonth() + 1)}${pad2(d.getDate())}-${pad2(d.getHours())}${pad2(d.getMinutes())}${pad2(d.getSeconds())}`;
+}
+function slug(s) {
+    return s.replace(/[^a-zA-Z0-9\u4e00-\u9fa5._-]+/g, "-").replace(/^-+|-+$/g, "") || "app";
+}
+function shortId(taskId) {
+    return taskId.replace(/-/g, "").slice(0, 8);
+}
+/** 从单步工具 outputs 中提取可读文本（chat 的 text、Dify raw_content 等） */
+function extractReadableText(outputs) {
+    if (outputs == null)
+        return null;
+    if (typeof outputs === "string")
+        return outputs.trim() || null;
+    if (typeof outputs !== "object")
+        return String(outputs);
+    const o = outputs;
+    if (typeof o.text === "string" && o.text.trim())
+        return o.text.trim();
+    if (typeof o.message === "string" && o.message.trim())
+        return o.message.trim();
+    const raw = o.raw_content;
+    if (Array.isArray(raw)) {
+        const parts = [];
+        for (const item of raw) {
+            if (!item || typeof item !== "object")
+                continue;
+            const it = item;
+            if (it.type === "text" && typeof it.text === "string")
+                parts.push(it.text);
+        }
+        if (parts.length)
+            return parts.join("\n\n");
+    }
+    return null;
+}
+function collectHttpsUrls(val, acc, depth = 0) {
+    if (depth > 12)
+        return;
+    if (val == null)
+        return;
+    if (typeof val === "string" && /^https?:\/\//.test(val)) {
+        acc.add(val);
+        return;
+    }
+    if (Array.isArray(val)) {
+        for (const x of val)
+            collectHttpsUrls(x, acc, depth + 1);
+        return;
+    }
+    if (typeof val === "object") {
+        const o = val;
+        for (const k of ["url", "uri"]) {
+            const v = o[k];
+            if (typeof v === "string" && /^https?:\/\//.test(v))
+                acc.add(v);
+        }
+        for (const v of Object.values(o))
+            collectHttpsUrls(v, acc, depth + 1);
+    }
+}
+function labelForOutputKey(key) {
+    const map = {
+        product: "原始商品图",
+        cutout: "透明底商品图",
+        mask: "抠图 Mask",
+        mask_url: "抠图 Mask",
+        hero: "商品主图",
+        main_image: "商品主图",
+        selling_point_image: "卖点图",
+        detail_image: "细节图",
+        lifestyle_image: "生活方式图",
+        cover_image: "小红书封面图",
+        xhs: "小红书种草图",
+        xhs_seed_image: "小红书种草图",
+        hero_module: "首屏模块",
+        pain_point_module: "痛点模块",
+        structure_module: "结构细节模块",
+        usage_module: "使用场景模块",
+        comparison_module: "对比规格模块",
+        scene: "生成场景图",
+        scene_image: "场景图",
+        video: "生成视频",
+        source: "原始素材",
+        uploaded: "上传后的素材",
+        listing: "上架素材",
+        poster: "商品海报",
+    };
+    return map[key.toLowerCase()] ?? key;
+}
+function collectLabeledUrls(outputs) {
+    if (!outputs || typeof outputs !== "object" || Array.isArray(outputs)) {
+        const urls = new Set();
+        collectHttpsUrls(outputs, urls);
+        return [...urls].map((url) => ({ label: "资源", url }));
+    }
+    const o = outputs;
+    const labeled = [];
+    const seen = new Set();
+    const push = (label, url) => {
+        if (typeof url !== "string" || !/^https?:\/\//.test(url) || seen.has(url))
+            return;
+        seen.add(url);
+        labeled.push({ label, url });
+    };
+    if (Array.isArray(o.assets)) {
+        for (const item of o.assets) {
+            if (!item || typeof item !== "object")
+                continue;
+            const asset = item;
+            push(typeof asset.label === "string" && asset.label.trim() ? asset.label.trim() : "资源", asset.url);
+        }
+    }
+    for (const [key, value] of Object.entries(o)) {
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            push(labelForOutputKey(key), value.url);
+        }
+    }
+    const urls = new Set();
+    collectHttpsUrls(outputs, urls);
+    for (const url of urls) {
+        push("资源", url);
+    }
+    return labeled;
+}
+function collectTextSections(outputs) {
+    if (!outputs || typeof outputs !== "object" || Array.isArray(outputs))
+        return [];
+    const o = outputs;
+    const sections = [];
+    const push = (label, value) => {
+        if (typeof value !== "string")
+            return;
+        const text = value.trim();
+        if (!text)
+            return;
+        sections.push({ label, text });
+    };
+    push("标题", o.title_text);
+    push("小红书种草文案", o.xhs_caption);
+    push("交付说明", o.delivery_copy);
+    push("商品主图提示词", o.main_image_prompt);
+    push("小红书种草图提示词", o.xhs_seed_prompt);
+    push("素材规划", o.prompt_plan);
+    push("文案模式", formatObjectText(o.copy_plan));
+    push("图上/后期文案建议", formatObjectText(o.overlay_copy));
+    if (sections.length === 0)
+        push("文案与说明", extractReadableText(outputs));
+    return sections;
+}
+function formatObjectText(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const entries = Object.entries(value)
+        .filter(([, item]) => item !== undefined && item !== null && String(item).trim())
+        .map(([key, item]) => `- ${key}: ${String(item)}`);
+    return entries.length > 0 ? entries.join("\n") : undefined;
+}
+function extFromUrl(u) {
+    try {
+        const path = new URL(u).pathname.toLowerCase();
+        const m = path.match(/\.(png|jpe?g|gif|webp|svg|mp4|webm)$/);
+        if (m)
+            return `.${m[1] === "jpeg" ? "jpg" : m[1]}`;
+    }
+    catch {
+        /* ignore */
+    }
+    return ".bin";
+}
+async function downloadToFile(url, filePath) {
+    try {
+        const safeUrl = assertSafeHttpUrl(url, { context: "交付物资源 URL" });
+        const res = await fetch(safeUrl, {
+            headers: { "User-Agent": "gd-cli-deliverables/1.0" },
+            signal: AbortSignal.timeout(120_000),
+        });
+        if (!res.ok)
+            return { ok: false, reason: `HTTP ${res.status}` };
+        const buf = Buffer.from(await res.arrayBuffer());
+        await writeFile(filePath, buf);
+        return { ok: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: redactSensitiveText(error instanceof Error ? error.message : String(error)),
+        };
+    }
+}
+async function downloadLabeledImageUrls(urls, imagesDir, fallbackName, startIndex = 0) {
+    let imgIdx = startIndex;
+    for (const item of urls) {
+        const u = item.url;
+        const label = item.label || fallbackName;
+        const kind = guessUrlKind(u);
+        if (kind !== "image")
+            continue;
+        imgIdx += 1;
+        const ext = extFromUrl(u);
+        const fn = join(imagesDir, `${pad2(imgIdx)}-${slug(label)}${ext}`);
+        const result = await downloadToFile(u, fn);
+        if (!result.ok) {
+            await writeFile(`${fn}.url.txt`, `下载失败：${result.reason ?? "未知错误"}\n请手动打开：\n${redactSensitiveText(u)}\n`, "utf8");
+        }
+    }
+    return imgIdx;
+}
+function invocationToMarkdown(step, inv) {
+    const lines = [
+        `# ${step.step_name}`,
+        "",
+        `- **步骤**: ${step.step_order}`,
+        `- **节点 ID**: \`${step.step_id}\``,
+        `- **工具**: \`${step.tool}\``,
+        "",
+    ];
+    const status = inv.status;
+    const taskId = inv.task_id;
+    if (taskId)
+        lines.push(`- **子任务 ID**: \`${taskId}\``, "");
+    if (status)
+        lines.push(`- **状态**: ${String(status)}`, "");
+    if (inv.error != null) {
+        lines.push("## 错误", "", "```json", JSON.stringify(inv.error, null, 2), "```", "");
+    }
+    const outputs = inv.outputs;
+    const body = extractReadableText(outputs);
+    if (body) {
+        lines.push("## 文本结果", "", body, "");
+    }
+    const urls = new Set();
+    collectHttpsUrls(outputs, urls);
+    const urlList = [...urls];
+    if (urlList.length) {
+        lines.push("## 链接与资源", "");
+        for (const u of urlList) {
+            lines.push(`- ${u}`);
+        }
+        lines.push("");
+    }
+    if (!body && outputs != null && typeof outputs === "object") {
+        lines.push("## 原始输出（JSON）", "", "```json", JSON.stringify(outputs, null, 2), "```", "");
+    }
+    return lines.join("\n");
+}
+function parseStepOutputs(outputs) {
+    if (!outputs || typeof outputs !== "object")
+        return null;
+    const o = outputs;
+    const raw = o.step_outputs;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return null;
+    const out = [];
+    for (const row of raw) {
+        if (!row || typeof row !== "object")
+            continue;
+        const r = row;
+        const inv = r.invocation;
+        if (!inv || typeof inv !== "object")
+            continue;
+        out.push({
+            step_order: Number(r.step_order) || out.length + 1,
+            step_id: String(r.step_id ?? ""),
+            step_name: String(r.step_name ?? ""),
+            tool: String(r.tool ?? ""),
+            invocation: inv,
+        });
+    }
+    return out.length ? out : null;
+}
+/**
+ * 将 App 完成后的 outputs 落盘：每步一个 Markdown、图片下载到 images/、打 zip。
+ */
+export async function writeAppDeliverables(opts) {
+    const { appId, taskId, outputs, outputDir, activityLabel } = opts;
+    const root = resolveSafeOutputDir(outputDir);
+    await mkdir(root, { recursive: true });
+    const folderName = `${slug(appId)}-${shortId(taskId)}-${nowStamp()}`;
+    const created = await createUniqueOutputDir(root, folderName);
+    const dir = created.dir;
+    const imagesDir = join(dir, "images");
+    await mkdir(imagesDir, { recursive: true });
+    const label = activityLabel?.trim() || appId;
+    const steps = parseStepOutputs(outputs) ?? [];
+    if (steps.length > 0) {
+        let imgIdx = 0;
+        for (const step of steps) {
+            const stepTitle = step.step_name || labelForOutputKey(step.step_id || step.tool);
+            const baseName = `${pad2(step.step_order)}-${slug(stepTitle)}`;
+            const mdPath = join(dir, `${baseName}.md`);
+            const md = invocationToMarkdown(step, step.invocation);
+            await writeFile(mdPath, md, "utf8");
+            const outs = step.invocation.outputs;
+            const labeledUrls = collectLabeledUrls(outs).map((item) => ({
+                label: item.label === "资源" ? stepTitle : item.label,
+                url: item.url,
+            }));
+            imgIdx = await downloadLabeledImageUrls(labeledUrls, imagesDir, stepTitle, imgIdx);
+        }
+    }
+    else {
+        /** 无 step_outputs 时退化为整包 JSON + 链接列表 */
+        const fallback = join(dir, "交付结果汇总.md");
+        const labeledUrls = collectLabeledUrls(outputs);
+        const textSections = collectTextSections(outputs);
+        const text = typeof outputs === "object" && outputs !== null
+            ? JSON.stringify(outputs, null, 2)
+            : String(outputs);
+        await downloadLabeledImageUrls(labeledUrls, imagesDir, "交付资源");
+        const textMarkdown = textSections.length > 0
+            ? `## 文案与提示词\n\n${textSections.map(({ label, text }) => `### ${label}\n\n${text}`).join("\n\n")}\n\n`
+            : "";
+        await writeFile(fallback, `# 运行结果汇总\n\n${textMarkdown}## 链接\n\n${labeledUrls.map(({ label, url }) => `- **${label}**: ${url}`).join("\n") || "(无)"}\n\n## 完整 outputs\n\n\`\`\`json\n${text}\n\`\`\`\n`, "utf8");
+    }
+    const readmePath = join(dir, "README.md");
+    const zipName = `${created.name}.zip`;
+    const zipPath = join(root, zipName);
+    const readme = buildReadmeMd({
+        label,
+        appId,
+        taskId,
+        zipPath,
+        stepCount: steps.length || 1,
+    });
+    await writeFile(readmePath, readme, "utf8");
+    await zipDirectory(dir, zipPath);
+    return { dir, zipPath, readmePath };
+}
+function guessUrlKind(url) {
+    const u = url.toLowerCase();
+    if (/\.(png|jpe?g|gif|webp|svg)(\?|$)/.test(u))
+        return "image";
+    if (/\/image\//.test(u))
+        return "image";
+    return "other";
+}
+function buildReadmeMd(p) {
+    const lines = [
+        `# ${p.label} · 交付说明`,
+        "",
+        `- **应用 ID**: \`${p.appId}\``,
+        `- **任务 ID**: \`${p.taskId}\``,
+        `- **生成时间**: ${new Date().toISOString()}`,
+        `- **分步文件数**: ${p.stepCount}`,
+        "",
+        "## 目录结构",
+        "",
+        "- `README.md` — 本说明",
+        "- `*.md` — 各步骤文本结果（Markdown）",
+        "- `images/` — 从链接下载的图片（若下载失败会有 `.url.txt`）",
+        "",
+        "## 压缩包",
+        "",
+        `同级目录已生成 **${basename(p.zipPath)}**，可直接分发或上传。`,
+        "",
+        "---",
+        "",
+        "*由 GD CLI `gd-cli workflows run` 自动生成。*",
+        "",
+    ];
+    return lines.join("\n");
+}
+function zipDirectory(sourceDir, zipPath) {
+    return new Promise((resolvePromise, reject) => {
+        const output = createWriteStream(zipPath);
+        const archive = new ZipArchive({ zlib: { level: 9 } });
+        output.on("close", () => resolvePromise());
+        archive.on("error", (err) => reject(err));
+        archive.pipe(output);
+        archive.directory(sourceDir, false);
+        archive.finalize();
+    });
+}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "gaoding-cli",
+  "version": "1.0.0-alpha.5",
+  "description": "稿定 GD CLI - Tools / Workflows / DAM 命令行工具",
+  "license": "MIT",
+  "author": "Gaoding",
+  "type": "module",
+  "main": "./dist/src/program.js",
+  "types": "./dist/src/program.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/program.d.ts",
+      "import": "./dist/src/program.js"
+    }
+  },
+  "bin": {
+    "gd-cli": "dist/bin/gd-cli.js"
+  },
+  "files": [
+    "dist/",
+    "!dist/src/commands/app.*",
+    "!dist/src/commands/config.*",
+    "!dist/src/commands/config-env.*",
+    "!dist/src/commands/info.*",
+    "!dist/src/commands/search.*",
+    "!dist/src/commands/task.*",
+    "!dist/src/commands/tool.*",
+    "skills/gd-cli/",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/bin/gd-cli.js",
+    "dev": "node scripts/install-dev-bin.mjs --quiet && tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "dev:setup": "node scripts/install-dev-bin.mjs",
+    "start": "tsx bin/gd-cli.ts",
+    "sso:probe": "tsx scripts/sso-probe.ts",
+    "smoke:cli": "npm run build && tsx scripts/cli-smoke-test.ts",
+    "smoke:cli:live": "npm run build && tsx scripts/cli-smoke-test.ts --live",
+    "test:package": "npm run build && node scripts/package-integration-test.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build && npm run smoke:cli && npm run test:package"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
+    "ali-oss": "^6.23.0",
+    "archiver": "^8.0.0",
+    "chalk": "^5.4.1",
+    "cli-table3": "^0.6.5",
+    "commander": "^13.1.0",
+    "log-update": "^6.1.0",
+    "open": "^10.1.2",
+    "ora": "^8.2.0",
+    "qrcode": "^1.5.4",
+    "sharp": "^0.34.5",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "@types/ali-oss": "^6.23.3",
+    "@types/archiver": "^8.0.0",
+    "@types/node": "^22.14.1",
+    "@types/qrcode": "^1.5.6",
+    "@types/uuid": "^10.0.0",
+    "eslint": "^9.24.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.50.0",
+    "vite": "^6.4.3",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "gaoding",
+    "gd-cli",
+    "cli",
+    "visual-creation",
+    "ai-tools",
+    "dam"
+  ]
+}

package/skills/gd-cli/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: gd-cli
+description: 当用户需要使用稿定生成图片、视频、电商素材或管理 DAM 素材时，优先使用本地 gd-cli 完成能力发现、调用、等待和交付。
+---
+
+# GD CLI Agent Skill
+
+## 执行原则
+
+当用户提出图片、视频、电商物料或 DAM 素材需求时，优先使用本地 `gd-cli` 调用稿定能力。不要因为当前 Agent 的工具列表中没有稿定工具，就改用本地 Canvas、ffmpeg、SVG 或未文档化接口。
+
+开始执行前：
+
+- 先读 `references/sop.md`。
+- 授权问题读 `references/auth.md`。
+- 组织选择读 `references/org.md`。
+- 权益不足或余额查询读 `references/entitlement.md`。
+- 错误处理和停止规则读 `references/errors.md`。
+- 图片、视频和交付包处理读 `references/deliverables.md`。
+- CLI 与 Skill 升级读 `references/update.md`。
+- 单点能力读 `references/tools.md`，多步骤场景读 `references/workflows.md`。
+
+Agent 只根据公开的 `tools`、`workflows` 和 `dam` 命令完成用户需求。普通生成任务中不要切换组织、环境或模型，不要调用内部运行时类、`raw.dify` 或未文档化接口。
+
+## 能力选择
+
+先读取能力列表，再按用户意图匹配：
+
+```bash
+gd-cli tools list --format json
+gd-cli workflows list --format json
+```
+
+| 用户意图 | 命令 |
+| --- | --- |
+| 生图、商品主图、海报、场景图 | `gd-cli tools call image.generate` |
+| 抠图、去背景、透明底 | `gd-cli tools call image.cutout` |
+| 高清、放大、变清晰 | `gd-cli tools call image.super-res` |
+| 文生视频、图生视频、动画短片 | `gd-cli tools call video.generate` |
+| Listing、商品图库、上架素材 | `gd-cli workflows run listing-gallery` |
+| 详情页、A+、PDP | `gd-cli workflows run pdp-a-plus` |
+| 小红书种草图文 | `gd-cli workflows run social-seeding-pack` |
+| Campaign KV、多渠道素材 | `gd-cli workflows run campaign-kv-pack` |
+
+复杂输入优先通过 `--input <json-file>` 或 stdin 传入。Agent 解析结果时使用 `--format json`，最终回复按 `references/deliverables.md` 展示预览、链接或文件，不要直接转发整段原始 JSON。
+
+## 参考资料
+
+- `references/sop.md`
+- `references/auth.md`
+- `references/org.md`
+- `references/entitlement.md`
+- `references/errors.md`
+- `references/deliverables.md`
+- `references/update.md`
+- `references/tools.md`
+- `references/workflows.md`

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

@@ -0,0 +1,31 @@
+# GD CLI Auth SOP
+
+## 未登录
+
+在 Agent 或非 TTY Shell 中执行：
+
+```bash
+gd-cli auth login --no-browser --format json
+```
+
+命令会输出包含以下字段的授权信息：
+
+- `type=device_authorization`
+- `verification_uri_complete`
+- `expires_in`
+- `interval`
+
+Agent 必须立即把 `verification_uri_complete` 原样发送给用户，并保持授权进程运行。用户完成授权后，再执行：
+
+```bash
+gd-cli auth status --format json
+```
+
+## 禁止动作
+
+- 不向用户索要 Token、Cookie 或 AK/SK。
+- 不用 Agent 沙箱浏览器代替用户完成 OAuth。
+- 不擅自结束仍在等待授权的进程。
+- 授权链接过期后，重新执行登录命令并发送新链接。
+
+如果授权完成但缺少组织，按 `org.md` 处理。

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

@@ -0,0 +1,22 @@
+# GD CLI Deliverables SOP
+
+## 解析字段
+
+优先读取：
+
+- `assets[]`
+- `outputs.assets[]`
+- `outputs.url`
+- `outputs.*.url`
+- `deliverable_dir`
+- `deliverable_zip`
+- `deliverable_readme`
+
+递归查找 `url` 或 `uri`，区分图片、视频和普通文件。
+
+## 交付方式
+
+- 当前 Agent 支持 Markdown 图片预览时，使用 `![生成图片](https://...)` 直接展示。
+- 视频不能内嵌播放时，提供可点击链接；有封面图时先展示封面。
+- 存在 `deliverable_zip` 时，明确说明这是完整交付包。Agent 支持附件时优先交付文件，否则提供本地路径或下载 URL。
+- 不把整段原始 JSON 作为最终回复。

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

@@ -0,0 +1,21 @@
+# GD CLI Entitlement SOP
+
+## 权益不足
+
+当错误码为 `ENTITLEMENT_INSUFFICIENT` 或 `QUOTA_EXCEEDED` 时，停止当前生成任务并说明：
+
+- 当前账号或组织权益不足，本次生成无法继续。
+- 优先提供 JSON 中的 `pricing_url`；没有时使用 `https://www.gaoding.com/pricing`。
+- 用户也可以明确选择一个有权益的组织后继续。
+
+不要自行切换组织、环境或模型，也不要循环试错。
+
+## 查询稿豆余额
+
+用户询问剩余稿豆、权益余额、还能生成几次或 usage 时，执行：
+
+```bash
+gd-cli usage --format json
+```
+
+只根据 `organization`、`credits.total`、`credits.used`、`credits.wait` 和 `credits.surplus` 回复。若用户要求查看其他组织，先执行 `gd-cli org list --format json`，等待用户明确选择后再切换。

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

@@ -0,0 +1,19 @@
+# GD CLI Error SOP
+
+## 停止规则
+
+1. 命令非零退出时，先解析 stdout 中的 JSON envelope。
+2. 优先读取 `error.code`、`error.message`、`error.hint`、`error.next_steps`、`pricing_url` 和 `retryable`。
+3. `retryable=false` 或未提供 `retryable` 时，不重复执行同一失败命令。
+4. 只有 `NETWORK_TRANSIENT` 可以短暂重试一次；第二次失败必须停止。
+5. `TOOL_ROUTE_UNAVAILABLE`、`ENTITLEMENT_INSUFFICIENT`、参数错误、授权错误和组织错误都不能盲目重试。
+
+## 禁止扩展诊断
+
+除非用户明确要求诊断，否则失败后不要切换组织、模型或环境，不查询 `raw.dify`，也不探测未文档化接口。
+
+## 回复结构
+
+- 发生了什么：使用 `error.message`。
+- 用户下一步：使用 `error.hint`、`error.next_steps`、`pricing_url` 或授权链接。
+- 不向用户复述 Agent 内部执行约束。

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

@@ -0,0 +1,18 @@
+# GD CLI Organization SOP
+
+## 组织选择边界
+
+Agent 可以读取组织，但不能替用户选择组织：
+
+```bash
+gd-cli org list --format json
+gd-cli org current --format json
+```
+
+只有用户明确选择具体组织后，才执行：
+
+```bash
+gd-cli org switch --org <org-id> --format json
+```
+
+如果 `org list` 返回多个组织，向用户列出组织名称、组织 ID 和当前状态，然后等待选择。不要根据名称、权益、历史记录或猜测自动切换。

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

@@ -0,0 +1,25 @@
+# GD CLI Agent SOP
+
+## 总规则
+
+1. 用户要图片、视频、电商物料或 DAM 素材时，优先使用 `gd-cli`。
+2. 需要解析结果、错误、URL、`task_id` 或 schema 时，使用 `--format json`。
+3. stdout JSON 用于解析结果，stderr 仅用于进度和排错。
+4. 普通生成任务只使用公开的 `tools`、`workflows` 和 `dam` 命令。
+5. 不替用户切换组织、环境或模型；涉及账号、组织、充值或授权时，把选择交给用户。
+
+## 推荐流程
+
+1. 必要时执行 `gd-cli auth status --format json` 检查授权状态。
+2. 未登录时按 `auth.md` 发起授权，并立即把授权链接交给用户。
+3. 使用 `gd-cli manifest --format json`、`gd-cli tools list --format json` 和 `gd-cli workflows list --format json` 发现能力。
+4. 单项处理选择 Tool，多步骤交付选择 Workflow。
+5. 执行命令后等待终态，解析 `status`、`outputs`、`assets`、`task_id` 和交付路径。
+6. 按 `deliverables.md` 交付预览、链接、本地文件或完整交付包。
+
+## 调用边界
+
+- 用户未指定模型时，直接调用目标能力，不主动查询或切换模型。
+- 用户未要求诊断时，不探测内部 endpoint、工具路由或组织权限。
+- 一次调用失败后按 `errors.md` 处理，不扩展为无关诊断。
+- Workflow 可能连续调用多个 Tool；不要在 Workflow 运行中并行发起重复任务。