@solgridai/cli 0.2.0-beta.0 → 0.2.0-beta.2

package/README.md

@@ -13,6 +13,19 @@ npm install -g @solgridai/cli
 solgrid --version
 ```
 
+### 测试版
+
+新版本正式发布前，会先以测试版（例如 `0.2.0-beta.0`）发布到 npm 的 `beta` 标签，用于提前试用新功能。直接执行 `npm install -g @solgridai/cli` 不会装到测试版。
+
+```bash
+npm install -g @solgridai/cli@beta           # 安装最新的测试版
+npm install -g @solgridai/cli@0.2.0-beta.0   # 或指定版本
+solgrid --version
+npm install -g @solgridai/cli                # 装回正式版
+```
+
+测试版的新功能可能依赖还没上线到生产环境的接口。这时请按发布说明，用 `SOLGRID_API_BASE_URL` 指向对应的环境，并使用该环境的 API Key（见[配置](#配置)）。
+
 ## 快速开始
 
 ```bash
@@ -45,7 +58,7 @@ solgrid run -p <provider> -e <endpoint> -i '{"screen_name":"nasa"}' --wait
 | `files get -i <fileId>` | 查看文件的类型、大小和状态 |
 | `files url -i <fileId>` | 为已上传的文件重新签发 24 小时有效的 URL |
 | `files download -i <fileId> [-o path] [--force]` | 通过签名 URL 下载文件到本地 |
-| `skills list [-q text] [--kind k] [--mine] [-l n] [--page n]` | 在 SkillHub 搜索 Skill（匹配标题和标签） |
+| `skills list [-q text] [--kind k] [--mine] [-l n] [--page n]` | 在 SkillHub 搜索 Skill（`-q` 按标题搜索） |
 | `skills get (-s slug \| -i id)` | 查看 Skill 详情 |
 | `skills tags` | 列出 Skill 可用的标签 |
 | `skills create [-s slug] -t <title> --kind <k> -d <text> (--dir <dir> \| --zip <file>) [--cover f] [--preview f] [--tag id]… [-y]` | 发布 Skill，创建后立即公开 |
@@ -89,8 +102,8 @@ solgrid skills create -t "Mecha portrait" --kind image \
 
   用 `--dir` 时 slug 默认取 `name`，传了 `-s` 就必须和 `name` 一致；用 `--zip` 时必须传 `-s`，由服务端核对。`skills update` 换包时，新包的 `name` 也必须等于原来的 slug。
 - `-d` 是显示在标题下的简短描述（纯文本，不按 Markdown 渲染）。Skill 的详细说明请写在 `SKILL.md` 里。
-- `--kind` 表示 Skill 产出的作品类型：`image`、`video`、`web`、`audio`。除视频外都需要封面（`--cover`）；视频和音频需要预览（`--preview`，图片、视频或音频）。
-- `--tag` 填 `solgrid skills tags` 列出的标签 ID，最多 3 个。
+- `--kind` 表示 Skill 产出的作品类型：`image`、`video`、`web`、`audio`。除视频外都需要封面（`--cover`，图片）。预览（`--preview`）的类型由 kind 决定：图片和网页类可选，只能是图片；视频类必填，只能是视频；音频类必填，只能是音频。
+- `--tag` 填 `solgrid skills tags` 列出的标签 ID，最多 3 个，不能重复。
 - `create`、`delete` 会先请你确认；在脚本或 Agent 中使用时加 `-y`。
 - `update` 只修改传入的选项；`--tag` 会替换全部标签，`--clear-tags` 清空标签，`--clear-preview` 去掉预览（仅图片和网页类 Skill）。只能修改、删除自己的 Skill。
 
@@ -119,6 +132,7 @@ solgrid run -p <provider> -e <endpoint> -i '<同样的输入>' --idempotency-key
 | `~/.config/solgrid/cli/config.json` | 当前激活的 key |
 | `SOLGRID_API_KEY` | 设置后优先于本机保存的 key，适合 CI 和 Agent |
 | `SOLGRID_API_BASE_URL` | 覆盖 API 地址，默认为 `https://api.solgrid.ai` |
+| `SOLGRID_LANG` / `--lang` | 服务端返回文本（标签名、错误信息）的语言：`en`（默认）或 `zh`；`--lang` 是全局选项，优先于环境变量。标签 ID、错误键和 CLI 自身的提示不变 |
 | `NO_COLOR` / `FORCE_COLOR` | 关闭或强制彩色输出 |
 
 ## 开发

package/dist/index.js

@@ -2075,7 +2075,7 @@ function useColor() {
 // node_modules/commander/index.js
 var program = new Command;
 // src/build-info.ts
-var buildInfo = { packageName: "@solgridai/cli", version: "0.2.0-beta.0" };
+var buildInfo = { packageName: "@solgridai/cli", version: "0.2.0-beta.2" };
 
 // src/core/errors.ts
 class CliError extends Error {
@@ -2104,6 +2104,7 @@ class CliError extends Error {
 class ApiError extends CliError {
   status;
   key;
+  keyDetail;
   routeMissing;
   apiKeySentTo;
   signedUrl;
@@ -2112,6 +2113,7 @@ class ApiError extends CliError {
     this.name = "ApiError";
     this.status = options.status;
     this.key = options.key;
+    this.keyDetail = options.keyDetail;
     this.routeMissing = options.routeMissing === true;
     this.apiKeySentTo = options.apiKeySentTo;
     this.signedUrl = options.signedUrl === true;
@@ -2120,6 +2122,7 @@ class ApiError extends CliError {
     return new ApiError(this.code, this.message, {
       ...this.status !== undefined ? { status: this.status } : {},
       ...this.key ? { key: this.key } : {},
+      ...this.keyDetail ? { keyDetail: this.keyDetail } : {},
       routeMissing: this.routeMissing,
       ...this.apiKeySentTo ? { apiKeySentTo: this.apiKeySentTo } : {},
       signedUrl: this.signedUrl,
@@ -2341,8 +2344,10 @@ var CONSOLE_URLS = {
 };
 var ENV = {
   apiKey: "SOLGRID_API_KEY",
-  apiBaseUrl: "SOLGRID_API_BASE_URL"
+  apiBaseUrl: "SOLGRID_API_BASE_URL",
+  language: "SOLGRID_LANG"
 };
+var LANGUAGES = ["en", "zh"];
 
 // src/core/config.ts
 function resolveConfigDir(env, homeDir) {
@@ -2541,6 +2546,41 @@ function formatAmount(amount) {
   const sign = negative ? "-" : "";
   return amount.currency === "USD" ? `${sign}$${number}` : `${sign}${number} ${amount.currency}`;
 }
+function plainDecimal(value) {
+  if (!Number.isFinite(value))
+    return;
+  const text = String(value);
+  const match = /^(-?)(\d+)(?:\.(\d+))?e([+-]\d+)$/.exec(text);
+  if (!match)
+    return text;
+  const [, sign = "", whole = "", fraction = "", exponent = "0"] = match;
+  const digits = whole + fraction;
+  const point = whole.length + Number(exponent);
+  if (point <= 0)
+    return `${sign}0.${"0".repeat(-point)}${digits}`;
+  if (point >= digits.length)
+    return `${sign}${digits}${"0".repeat(point - digits.length)}`;
+  return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+}
+function ceilToSixDecimals(value) {
+  const decimal = typeof value === "number" ? plainDecimal(value) : value.trim();
+  if (decimal === undefined || !/^\d+(\.\d+)?$/.test(decimal))
+    return;
+  const [whole = "0", fraction = ""] = decimal.split(".");
+  let micros = BigInt(whole + fraction.slice(0, 6).padEnd(6, "0"));
+  if (/[1-9]/.test(fraction.slice(6)))
+    micros += 1n;
+  const text = micros.toString().padStart(7, "0");
+  return `${text.slice(0, -6)}.${text.slice(-6)}`;
+}
+function formatUnitPrice(amount) {
+  if (!amount || typeof amount.value !== "number" && typeof amount.value !== "string")
+    return "-";
+  const decimal = ceilToSixDecimals(amount.value);
+  if (decimal === undefined)
+    return formatAmount(amount);
+  return amount.currency === "USD" ? `$${decimal}` : `${decimal} ${amount.currency}`;
+}
 
 // src/core/api/client.ts
 var DEFAULT_TIMEOUT_MS = 30000;
@@ -2553,6 +2593,9 @@ class ApiClient {
     this.options = options;
     this.baseUrl = options.baseUrl.replace(/\/+$/, "");
   }
+  languageHeader() {
+    return this.options.language ? { "Accept-Language": this.options.language } : {};
+  }
   post(path, body = {}, headers = {}, request = {}) {
     return this.send("POST", path, {
       body: JSON.stringify(body),
@@ -2594,6 +2637,7 @@ class ApiClient {
         method: "GET",
         headers: {
           "X-Solgrid-Client": this.options.clientId,
+          ...this.languageHeader(),
           ...this.options.apiKey ? { Authorization: `Bearer ${this.options.apiKey}` } : {}
         },
         signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS)
@@ -2620,6 +2664,7 @@ class ApiClient {
         headers: {
           Accept: "application/json",
           "X-Solgrid-Client": this.options.clientId,
+          ...this.languageHeader(),
           ...this.options.apiKey ? { Authorization: `Bearer ${this.options.apiKey}` } : {},
           ...options.headers
         },
@@ -2664,6 +2709,7 @@ function envelopeError(response, envelope, text, url, auth) {
   const status = bodyCode ?? (response.ok ? 400 : response.status);
   const serverMessage = typeof envelope?.message === "string" && envelope.message ? envelope.message : undefined;
   const key = errorKeyOf(envelope);
+  const keyDetail = keyDetailOf(envelope);
   const details = [
     ...validationDetails(envelope?.errorData, key),
     ...frameworkErrorDetails(envelope?.errors)
@@ -2673,6 +2719,7 @@ function envelopeError(response, envelope, text, url, auth) {
   return new ApiError(errorCodeForStatus(status), message, {
     status,
     ...key ? { key } : {},
+    ...keyDetail ? { keyDetail } : {},
     ...auth,
     ...serverJsonHint ? { hint: serverJsonHint } : {},
     details
@@ -2688,10 +2735,20 @@ function hasSerializerErrors(errors) {
   const value = errors?.serializerErrors;
   return Array.isArray(value) ? value.length > 0 : typeof value === "string" && value.length > 0;
 }
+function keyItemOf(envelope) {
+  const items = Array.isArray(envelope?.errorData) ? envelope.errorData : [];
+  return items.find((entry) => entry && typeof entry === "object" && !entry.propertyName && typeof entry.errorCode === "string" && ERROR_KEY.test(entry.errorCode));
+}
+function keyDetailOf(envelope) {
+  const item = keyItemOf(envelope);
+  if (!item)
+    return;
+  const { errorCode: _code, errorMessage: _message, propertyName: _property, ...rest } = item;
+  return Object.keys(rest).length > 0 ? rest : undefined;
+}
 var ERROR_KEY = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/;
 function errorKeyOf(envelope) {
-  const items = Array.isArray(envelope?.errorData) ? envelope.errorData : [];
-  const item = items.find((entry) => entry && !entry.propertyName && typeof entry.errorCode === "string" && ERROR_KEY.test(entry.errorCode));
+  const item = keyItemOf(envelope);
   if (item?.errorCode)
     return item.errorCode;
   const message = envelope?.message;
@@ -2849,7 +2906,44 @@ function presentApiError(error) {
 `) || undefined;
   return { message: base.message, hint };
 }
+function isAmount(value) {
+  const amount = value;
+  return typeof amount === "object" && amount !== null && (typeof amount.value === "string" || typeof amount.value === "number");
+}
+var RAISE_BUDGET = `Raise or disable the daily budget at ${CONSOLE_URLS.budgets}`;
+function explainDailyBudget(detail) {
+  const { reason, spent, held, requestedReservation, dailyLimit, remaining } = detail ?? {};
+  const amounts = [spent, held, requestedReservation, dailyLimit, remaining];
+  if (!amounts.every(isAmount))
+    return;
+  const [spentText, heldText, needText, limitText, leftText] = amounts.map((amount) => formatAmount(amount));
+  switch (reason) {
+    case "daily_spend_limit_reached":
+      return {
+        message: `Today's spending (${spentText}) has reached the daily budget of ${limitText}.`,
+        hint: `${RAISE_BUDGET}, or try again tomorrow (the budget resets at 00:00 UTC).`
+      };
+    case "requested_reservation_exceeds_remaining_budget":
+      return {
+        message: `This run requires a reservation of ${needText}, more than the ${leftText} left of today's ${limitText} budget (${spentText} spent).`,
+        hint: RAISE_BUDGET
+      };
+    case "reservation_exceeds_remaining_budget":
+      return {
+        message: `Runs still in progress hold ${heldText} of today's ${limitText} budget, leaving ${leftText}; this run requires a reservation of ${needText}.`,
+        hint: `Wait for those runs to finish (what they do not use is released), then retry with the same idempotency key, or submit runs one at a time.
+${RAISE_BUDGET}`
+      };
+    default:
+      return;
+  }
+}
 function explain(error) {
+  if (error.key === "daily_budget_exceeded") {
+    const budget = explainDailyBudget(error.keyDetail);
+    if (budget)
+      return budget;
+  }
   const known = error.key ? KEY_PRESENTATIONS[error.key] : undefined;
   if (known)
     return known;
@@ -2977,6 +3071,7 @@ function createOutput(ctx, json) {
             message,
             ...cliError instanceof ApiError && cliError.status !== undefined ? { status: cliError.status } : {},
             ...cliError instanceof ApiError && cliError.key ? { key: cliError.key } : {},
+            ...cliError instanceof ApiError && cliError.keyDetail ? { detail: cliError.keyDetail } : {},
             ...cliError.details.length > 0 ? { details: cliError.details } : {},
             ...hint ? { hint } : {}
           },
@@ -3031,13 +3126,29 @@ function apiClient(ctx) {
     });
   }
   sentKeys.set(ctx, resolved);
+  const language = requestLanguage(ctx);
   return new ApiClient({
     baseUrl: ctx.env[ENV.apiBaseUrl]?.trim() || DEFAULT_API_BASE_URL,
     apiKey: resolved.key,
     clientId: `cli@${buildInfo.version}`,
+    ...language ? { language } : {},
     fetch: ctx.fetch
   });
 }
+function requestLanguage(ctx) {
+  const value = ctx.language ?? ctx.env[ENV.language]?.trim();
+  if (!value)
+    return;
+  return parseLanguage(value, ctx.language === undefined ? ENV.language : "--lang");
+}
+function parseLanguage(value, source = "--lang") {
+  const language = value.trim().toLowerCase();
+  if (LANGUAGES.includes(language))
+    return language;
+  throw new CliError("USAGE", `Unsupported language in ${source}: ${value}.`, {
+    hint: `Use one of: ${LANGUAGES.join(", ")}.`
+  });
+}
 function withAuthContext(ctx, error) {
   const key = sentKeys.get(ctx);
   if (!(error instanceof ApiError) || error.code !== "AUTH_FAILED" || !key)
@@ -4070,6 +4181,7 @@ function registerSessionIdCommand(program, ctx) {
 
 // src/commands/skills.ts
 import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
+import { basename as basename4 } from "node:path";
 
 // src/core/skill-markdown.ts
 var MAX_SKILL_NAME_LENGTH = 64;
@@ -4521,6 +4633,10 @@ async function listSkillTags(client) {
   return checked.tags;
 }
 function checkTags(tags, available) {
+  const repeated = [...new Set(tags.filter((tag, index) => tags.indexOf(tag) !== index))];
+  if (repeated.length > 0) {
+    throw new CliError("USAGE", `Tag${repeated.length > 1 ? "s" : ""} given more than once: ${repeated.join(", ")}.`, { hint: "Pass each --tag once." });
+  }
   if (tags.length > MAX_TAGS) {
     throw new CliError("USAGE", `A Skill takes at most ${MAX_TAGS} tags; ${tags.length} were given.`);
   }
@@ -4532,6 +4648,9 @@ function checkTags(tags, available) {
     });
   }
 }
+function previewKindFor(kind) {
+  return kind === "video" ? "video" : kind === "audio" ? "audio" : "image";
+}
 var PUBLIC_DISPLAY = "1";
 function prepareSkillFile(path, role) {
   let size;
@@ -4605,7 +4724,7 @@ function collect2(value, previous = []) {
 }
 function addContentOptions(command, required) {
   const note = required ? "" : " (replaces the current one)";
-  command.option("-t, --title <title>", `title${note}`).option("--kind <kind>", `what the Skill makes: ${SKILL_KINDS.join(", ")}${note}`, parseKind2).option("-d, --description <text>", `a short description shown under the title${note}`).option("--description-file <path>", "read the description from a file instead").option("--tag <id>", `a tag ID from \`solgrid skills tags\`; up to ${MAX_TAGS}, repeat for several${required ? "" : " (replaces all current tags)"}`, collect2).option("--cover <path>", `cover image; required unless the kind is video${note}`).option("--preview <path>", `preview image, video or audio; required for video and audio${note}`).option("--dir <path>", `a Skill directory with SKILL.md at its top, packed for you${note}`).option("--zip <path>", `or an already packed Skill (.zip with SKILL.md)${note}`);
+  command.option("-t, --title <title>", `title${note}`).option("--kind <kind>", `what the Skill makes: ${SKILL_KINDS.join(", ")}${note}`, parseKind2).option("-d, --description <text>", `a short description shown under the title${note}`).option("--description-file <path>", "read the description from a file instead").option("--tag <id>", `a tag ID from \`solgrid skills tags\`; up to ${MAX_TAGS}, repeat for several${required ? "" : " (replaces all current tags)"}`, collect2).option("--cover <path>", `cover image; required unless the kind is video${note}`).option("--preview <path>", `preview of what the Skill makes: an image for image and web Skills (optional), a video for video Skills, an audio file for audio Skills${note}`).option("--dir <path>", `a Skill directory with SKILL.md at its top, packed for you${note}`).option("--zip <path>", `or an already packed Skill (.zip with SKILL.md)${note}`);
   return command;
 }
 function readDescription(opts) {
@@ -4631,7 +4750,22 @@ function checkMedia(kind, hasCover, hasPreview) {
   }
   if ((kind === "video" || kind === "audio") && !hasPreview) {
     throw new CliError("USAGE", `${aSkill(kind)} needs a preview.`, {
-      hint: `Pass --preview <${kind} or image file>.`
+      hint: `Pass --preview <${previewKindFor(kind)} file>.`
+    });
+  }
+}
+var A_FILE = {
+  image: "an image",
+  video: "a video",
+  audio: "an audio file",
+  skill: "a Skill package"
+};
+function checkPreviewFile(kind, path) {
+  const { kind: fileKind } = prepareSkillFile(path, "preview");
+  const expected = previewKindFor(kind);
+  if (fileKind !== expected) {
+    throw new CliError("USAGE", `${aSkill(kind)}'s preview must be ${A_FILE[expected]}, not ${A_FILE[fileKind]}: ${basename4(path)}.`, {
+      hint: "Image and web Skills take an image preview, video Skills a video, audio Skills an audio file."
     });
   }
 }
@@ -4723,7 +4857,7 @@ function registerSkillsCommand(program, ctx) {
   const skills = program.command("skills").description("Find, publish and manage Skills on SkillHub.").addHelpText("after", `
 A Skill is public as soon as it is created. Its slug identifies it everywhere and cannot
 be changed later.`);
-  skills.command("list").description("Search Skills, newest first.").option("-q, --query <words>", "match titles and tags").option("--kind <kind>", `only this kind: ${SKILL_KINDS.join(", ")}`, parseKind2).option("--mine", "only your own Skills").option("-l, --limit <n>", "Skills per page (default 20, up to 100)", parsePositiveInt).option("--page <n>", "page number (default 1)", parsePositiveInt).option(...JSON_FLAG).action((opts) => runAction(ctx, opts.json, async (out) => {
+  skills.command("list").description("Search Skills, newest first.").option("-q, --query <words>", "search by title").option("--kind <kind>", `only this kind: ${SKILL_KINDS.join(", ")}`, parseKind2).option("--mine", "only your own Skills").option("-l, --limit <n>", "Skills per page (default 20, up to 100)", parsePositiveInt).option("--page <n>", "page number (default 1)", parsePositiveInt).option(...JSON_FLAG).action((opts) => runAction(ctx, opts.json, async (out) => {
     const client = apiClient(ctx);
     out.progress.start("Searching Skills…");
     const data = await listSkills(client, {
@@ -4788,7 +4922,7 @@ be changed later.`);
     if (opts.cover)
       prepareSkillFile(opts.cover, "cover");
     if (opts.preview)
-      prepareSkillFile(opts.preview, "preview");
+      checkPreviewFile(kind, opts.preview);
     const pkg = skillPackage(opts);
     try {
       const slug = slugFor(pkg, opts);
@@ -4869,8 +5003,9 @@ be changed later.`);
       if (pkg?.name !== undefined && pkg.name !== skill.slug) {
         throw nameMismatch(pkg.name, skill.slug);
       }
+      const current = contentOf(skill);
       const next = {
-        ...contentOf(skill),
+        ...current,
         ...opts.title !== undefined ? { title: opts.title } : {},
         ...opts.kind !== undefined ? { kind: opts.kind } : {},
         ...description !== undefined ? { description } : {},
@@ -4883,6 +5018,14 @@ be changed later.`);
         });
       }
       checkMedia(next.kind, Boolean(opts.cover ?? next.coverFileAssetId), Boolean(opts.preview ?? next.previewFileAssetId));
+      if (opts.preview) {
+        checkPreviewFile(next.kind, opts.preview);
+      } else if (next.previewFileAssetId && previewKindFor(current.kind) !== previewKindFor(next.kind)) {
+        const wanted = previewKindFor(next.kind);
+        throw new CliError("USAGE", `Changing this ${current.kind} Skill to ${next.kind} needs a new preview: the current one is ${A_FILE[previewKindFor(current.kind)]}.`, {
+          hint: `Pass --preview <${wanted} file>${wanted === "image" ? ", or --clear-preview" : ""}.`
+        });
+      }
       await checkTagOptions(client, out, opts.tag);
       next.skillFileAssetId = await uploadIfGiven(client, out, pkg?.path, "skill") ?? next.skillFileAssetId;
       next.coverFileAssetId = await uploadIfGiven(client, out, opts.cover, "cover") ?? next.coverFileAssetId;
@@ -4988,8 +5131,8 @@ function withUnit(amount, unit) {
   return unit ? `${amount} ${unit}` : amount;
 }
 function describeLeaf(leaf) {
-  const text = withUnit(formatAmount(leaf.amount), unitText(leaf));
-  return leaf.flatFee ? `${text} + ${formatAmount(leaf.flatFee)} flat` : text;
+  const text = withUnit(formatUnitPrice(leaf.amount), unitText(leaf));
+  return leaf.flatFee ? `${text} + ${formatUnitPrice(leaf.flatFee)} flat` : text;
 }
 var METER_UNITS = {
   Calls: ["call", "calls"],
@@ -5013,8 +5156,7 @@ function meterText(meter, size = 1) {
   return size === 1 ? `per ${one}` : `per ${countText(size)} ${many}`;
 }
 function rateAmount(rate) {
-  const micros = Math.ceil(Number((rate.unitPriceUsd * 1e6).toPrecision(12)));
-  return formatAmount({ value: (micros / 1e6).toFixed(6), currency: "USD" });
+  return formatUnitPrice({ value: rate.unitPriceUsd, currency: "USD" });
 }
 function describeRate(rate) {
   return `${rateAmount(rate)} ${meterText(rate.meter, rate.unitSize)}`;
@@ -5034,7 +5176,7 @@ function hasConditions(rate) {
 function summarizeRates(price, rates) {
   const only = rates.length === 1 ? rates[0] : undefined;
   if (only) {
-    const amount = price.amount ? formatAmount(price.amount) : rateAmount(only);
+    const amount = price.amount ? formatUnitPrice(price.amount) : rateAmount(only);
     const text = `${amount} ${meterText(only.meter, only.unitSize)}`;
     return hasConditions(only) ? `${text} (${conditionsText(only)})` : text;
   }
@@ -5069,20 +5211,20 @@ function summarizePrice(price, fallback) {
   switch (price.type) {
     case "PER_UNIT_MATRIX": {
       const first = price.variants?.[0]?.price;
-      text = `from ${withUnit(formatAmount(price.amount), first ? unitText(first) : "")}`;
+      text = `from ${withUnit(formatUnitPrice(price.amount), first ? unitText(first) : "")}`;
       break;
     }
     case "TIERED":
       text = price.default ? describeLeaf(price.default) : "varies";
       break;
     case "BY_PERIOD":
-      text = withUnit(formatAmount(price.amount), price.period ? periodText(price.period) : "");
+      text = withUnit(formatUnitPrice(price.amount), price.period ? periodText(price.period) : "");
       break;
     default:
-      text = withUnit(formatAmount(price.amount), unitText(price));
+      text = withUnit(formatUnitPrice(price.amount), unitText(price));
   }
   if (price.flatFee)
-    text += ` + ${formatAmount(price.flatFee)} flat`;
+    text += ` + ${formatUnitPrice(price.flatFee)} flat`;
   if (price.type === "TIERED" && price.tiers?.length)
     text += " + add-ons";
   return text;
@@ -5307,11 +5449,15 @@ function renderInput(input, legacySchema, style) {
 
 // src/program.ts
 function createProgram(ctx, options = {}) {
-  const program = new Command().name("solgrid").description("Discover, inspect and run Solgrid tools from your terminal or agent.").version(buildInfo.version, "-v, --version", "Print the CLI version.").helpOption("-h, --help", "Show help.").configureOutput({
+  const program = new Command().name("solgrid").description("Discover, inspect and run Solgrid tools from your terminal or agent.").version(buildInfo.version, "-v, --version", "Print the CLI version.").helpOption("-h, --help", "Show help.").option("--lang <code>", `language for text the Solgrid API writes, such as tag names and error messages: ${LANGUAGES.join(" or ")} (default: en; or set ${ENV.language})`).configureOutput({
     writeOut: (text) => ctx.stdout.write(text),
     writeErr: (text) => options.jsonErrors ? undefined : ctx.stderr.write(text),
     outputError: (text, write) => options.jsonErrors ? undefined : write(text)
-  }).showHelpAfterError("(run with --help for usage)").exitOverride();
+  }).showHelpAfterError("(run with --help for usage)").exitOverride().hook("preAction", () => {
+    const { lang } = program.opts();
+    if (lang !== undefined)
+      ctx.language = lang;
+  });
   registerToolCommands(program, ctx);
   registerRunCommand(program, ctx);
   registerRunsCommand(program, ctx);
@@ -5347,16 +5493,8 @@ async function runCli(ctx, args) {
   return ctx.exitCode;
 }
 function wantsJson(program, args) {
-  let command = program;
-  let index = 0;
-  for (;index < args.length; index++) {
-    const arg = args[index] ?? "";
-    const next = command.commands.find((sub) => sub.name() === arg || sub.aliases().includes(arg));
-    if (!next)
-      break;
-    command = next;
-  }
-  const rest = args.slice(index);
+  const { command, index, local } = resolveCommand(program, args);
+  const rest = local.slice(index);
   if (command.commands.length > 0) {
     const end = rest.indexOf("--");
     return (end === -1 ? rest : rest.slice(0, end)).some((arg) => arg === "--json" || /^-[A-Za-z]*j[A-Za-z]*$/.test(arg));
@@ -5394,14 +5532,39 @@ function wantsJson(program, args) {
   return false;
 }
 function withImplicitHelp(program, args) {
+  const { command, index, local } = resolveCommand(program, args);
+  if (index < local.length)
+    return args;
+  return command.commands.length > 0 ? [...args, "--help"] : args;
+}
+function resolveCommand(program, args) {
+  const local = [];
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i] ?? "";
+    if (arg === "--") {
+      local.push(...args.slice(i));
+      break;
+    }
+    const global = program.options.find((o) => o.long === arg || o.short === arg);
+    if (global) {
+      if (global.required)
+        i++;
+      continue;
+    }
+    if (program.options.some((o) => o.long !== undefined && arg.startsWith(`${o.long}=`)))
+      continue;
+    local.push(arg);
+  }
   let command = program;
-  for (const arg of args) {
+  let index = 0;
+  for (;index < local.length; index++) {
+    const arg = local[index] ?? "";
     const next = command.commands.find((sub) => sub.name() === arg || sub.aliases().includes(arg));
     if (!next)
-      return args;
+      break;
     command = next;
   }
-  return command.commands.length > 0 ? [...args, "--help"] : args;
+  return { command, index, local };
 }
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solgridai/cli",
-  "version": "0.2.0-beta.0",
+  "version": "0.2.0-beta.2",
   "description": "Command-line client for Solgrid: discover, inspect and run tools from your terminal or agent.",
   "license": "MIT",
   "repository": {

package/skills/solgrid-cli/SKILL.md

@@ -172,9 +172,18 @@ with the same key, or look the run up first.
   | `error.key` | Meaning |
   |---|---|
   | `wallet_balance_insufficient` | Balance too low; the user can top up on the console's Wallet page |
-  | `daily_budget_exceeded` | Daily budget reached; adjustable on the console's Budgets page |
+  | `daily_budget_exceeded` | Daily budget reached; adjustable on the console's Budgets page (but see below) |
   | `per_call_limit_exceeded` | The run costs more than the per-call limit; adjustable on the console's Budgets page |
 
+- The daily budget counts today's spending plus what runs still in progress
+  hold. If `daily_budget_exceeded` comes with
+  `error.detail.reason: "reservation_exceeds_remaining_budget"`, those holds
+  are the cause: wait for the user's runs in progress to finish, then retry
+  with the **same** idempotency key (a refused run was never started), or
+  submit runs one at a time. `error.detail` also has `spent`, `held`,
+  `requestedReservation`, `dailyLimit` and `remaining`.
+- The budget is checked when a run starts; a run's final cost can exceed what
+  it held, so a day's spending can end slightly over the budget.
 - Never top up the wallet or change budgets on the user's behalf.
 
 ## Using local files as input
@@ -206,7 +215,7 @@ Use these only when the user asks to publish, change or remove *their* Skill on
 SkillHub; finding and downloading Skills is always fine.
 
 ```bash
-solgrid skills list -q "<words>" --json        # search titles and tags
+solgrid skills list -q "<words>" --json        # search by title
 solgrid skills get -s <slug> --json             # details
 solgrid skills download -s <slug> -o <path>     # the Skill package (.zip)
 ```
@@ -239,11 +248,17 @@ solgrid skills create -t "<title>" --kind <image|video|web|audio> \
   --tag <tag-id> --yes --json
 ```
 
+Tag names come in English. To show them to a user in Chinese, add the global
+`--lang zh` (e.g. `solgrid skills tags --lang zh --json`); it also turns the
+server's error messages into Chinese. Always pass tag **IDs** to `--tag`.
+
 - A Skill is **public as soon as it is created**, and its slug can never be
   changed. Confirm the title, slug (the `name` in `SKILL.md`) and files with
   the user before passing `--yes`.
 - `--kind` is what the Skill produces. Every kind except `video` needs
-  `--cover`; `video` and `audio` need `--preview`.
+  `--cover` (an image). The `--preview` type follows the kind: an image for
+  `image` and `web` (optional), a video for `video`, an audio file for `audio`
+  (both required).
 - `-d` is a short plain-text line shown under the title; the Skill's real
   instructions belong in `SKILL.md`.
 - If the CLI refuses the directory, it says which rule it breaks (for example