@solgridai/cli 0.2.0-beta.1 → 0.2.0-beta.3

package/README.md

@@ -58,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，创建后立即公开 |
@@ -102,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。
 
@@ -132,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.1" };
+var buildInfo = { packageName: "@solgridai/cli", version: "0.2.0-beta.3" };
 
 // src/core/errors.ts
 class CliError extends Error {
@@ -2344,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) {
@@ -2591,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),
@@ -2632,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)
@@ -2658,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
         },
@@ -3119,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)
@@ -4158,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;
@@ -4609,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.`);
   }
@@ -4620,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;
@@ -4693,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) {
@@ -4719,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."
     });
   }
 }
@@ -4811,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, {
@@ -4848,7 +4894,8 @@ be changed later.`);
     const client = apiClient(ctx);
     out.progress.start("Fetching Skill…");
     const skill = await findSkill(client, target);
-    out.result(skill, () => renderSkill(skill, out.style));
+    const tagNames = opts.json ? undefined : await tagNamesFor(client, skill.tags);
+    out.result(skill, () => renderSkill(skill, out.style, tagNames));
   }));
   skills.command("tags").description(`List the tags a Skill can carry (up to ${MAX_TAGS} each).`).option(...JSON_FLAG).action((opts) => runAction(ctx, opts.json, async (out) => {
     const client = apiClient(ctx);
@@ -4876,7 +4923,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);
@@ -4957,8 +5004,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 } : {},
@@ -4971,6 +5019,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;
@@ -5019,7 +5075,20 @@ be changed later.`);
     out.result({ slug: opts.slug, path: destination, sizeBytes: bytes }, () => `Saved ${destination} (${formatBytes(bytes)}).`);
   }));
 }
-function renderSkill(skill, style) {
+async function tagNamesFor(client, tags) {
+  if (!tags?.length)
+    return;
+  try {
+    return new Map((await listSkillTags(client)).map((tag) => [tag.id, tag.name]));
+  } catch {
+    return;
+  }
+}
+function renderSkill(skill, style, tagNames) {
+  const tags = skill.tags?.map((id) => {
+    const name = tagNames?.get(id);
+    return name ? `${name} (${id})` : id;
+  });
   const lines = [
     style("bold", skill.title),
     "",
@@ -5027,8 +5096,8 @@ function renderSkill(skill, style) {
       ["Slug", skill.slug],
       ["ID", skill.id],
       ["Kind", kindName(skill.kind)],
-      ["Author", skill.author?.nickname || undefined],
-      ["Tags", skill.tags?.length ? skill.tags.join(", ") : undefined],
+      ["Author", skill.author?.nickname || "-"],
+      ["Tags", tags?.length ? tags.join(", ") : undefined],
       ["Created", skill.createdAt ? formatTime(skill.createdAt) : undefined],
       ["Updated", skill.updatedAt ? formatTime(skill.updatedAt) : undefined]
     ], style)
@@ -5394,11 +5463,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);
@@ -5434,16 +5507,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));
@@ -5481,14 +5546,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.1",
+  "version": "0.2.0-beta.3",
   "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

@@ -215,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)
 ```
@@ -248,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