@ai-agent-tools/picgen 0.1.0-alpha.4 → 0.1.0-alpha.8

package/README.md

@@ -26,15 +26,21 @@ npm run build
 ## Install
 
 ```bash
+node -v
+npm -v
 npm install -g @ai-agent-tools/picgen
+npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy
+picgen skill install codex
 picgen --help
 picgen quickstart
 ```
 
+Use `npx -y skills add ...` for cross-agent skill installation when supported. `picgen skill install codex` is a Codex-only fallback that copies the bundled skill into `~/.codex/skills/picgen`.
+
 Agent trial prompt:
 
 ```text
-请安装并体验 @ai-agent-tools/picgen：全局安装 npm install -g @ai-agent-tools/picgen，运行 picgen setup 配置，然后先 dry-run 预览，再确认生成一张测试图。如果我要用参考图，请使用 --reference <图片路径>。
+请帮我安装并配置 PicGen 生图工具。安装前请先检查这台电脑是否已经安装 Node.js 和 npm。如果没有安装，请先指导我安装 Node.js LTS 版本，并验证 node -v 和 npm -v 是否能正常显示版本号。然后执行 npm install -g @ai-agent-tools/picgen@latest 安装 CLI，再执行 npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy 安装 PicGen skill。如果 skills 安装器不可用且当前是 Codex，请改用 picgen skill install codex。然后引导我配置 provider 和 API key，先预览生成方案，等我确认后再生成测试图。
 ```
 
 For first-user rollout, see [docs/release-alpha.md](./docs/release-alpha.md).
@@ -44,6 +50,8 @@ For first-user rollout, see [docs/release-alpha.md](./docs/release-alpha.md).
 ```bash
 picgen setup
 picgen quickstart
+npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy
+picgen skill install codex
 picgen update check
 picgen doctor --json
 picgen create --dry-run "一张产品发布会主视觉"
@@ -52,6 +60,10 @@ picgen create --dry-run --provider gemini_official --reference ./reference.png "
 picgen create --yes --provider gemini_official --reference ./reference.png "基于参考图生成一张品牌海报"
 picgen provider list
 picgen provider add
+picgen provider quick-add gemini-proxy --host https://www.pandai.vip --prefer
+picgen key set PICGEN_GEMINI_PROXY_KEY --clipboard
+picgen key set PICGEN_GEMINI_PROXY_KEY --stdin
+picgen key list --json
 picgen provider test openai_official --json
 picgen provider prefer gemini_official
 picgen provider disable gemini_proxy
@@ -99,6 +111,8 @@ For non-technical users, `picgen setup` can save API keys for you in:
 
 PicGen loads this managed env file automatically. Shell environment variables take priority, and a project `.env` can override the managed file for local testing.
 
+When agents inspect key configuration, they should use `picgen key list/show` so chat output only contains masked key status. To inspect or edit the full saved key directly, open `~/.picgen/.env`; a project `.env` in the current directory may override it, and shell environment variables take highest priority.
+
 You can start from the included example:
 
 ```bash

package/dist/cli.js

@@ -217,12 +217,12 @@ function padMilliseconds(value) {
 function slug(value) {
   return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
 }
-function redactProviderImageData(value, key) {
+function redactProviderImageData(value, key2) {
   if (Array.isArray(value)) {
     return value.map((item) => redactProviderImageData(item));
   }
   if (!value || typeof value !== "object") {
-    return shouldRedactImageDataKey(key) && typeof value === "string" ? redactedProviderDataPlaceholder(value) : value;
+    return shouldRedactImageDataKey(key2) && typeof value === "string" ? redactedProviderDataPlaceholder(value) : value;
   }
   return Object.fromEntries(
     Object.entries(value).map(([entryKey, entryValue]) => [
@@ -231,8 +231,8 @@ function redactProviderImageData(value, key) {
     ])
   );
 }
-function shouldRedactImageDataKey(key) {
-  return key === "b64_json" || key === "data" || key === "thoughtSignature" || key === "thought_signature";
+function shouldRedactImageDataKey(key2) {
+  return key2 === "b64_json" || key2 === "data" || key2 === "thoughtSignature" || key2 === "thought_signature";
 }
 function redactedProviderDataPlaceholder(value) {
   return `[redacted provider data: ${value.length} chars]`;
@@ -1054,7 +1054,7 @@ import { homedir as homedir2 } from "os";
 
 // src/version.ts
 var PACKAGE_NAME = "@ai-agent-tools/picgen";
-var VERSION = "0.1.0-alpha.4";
+var VERSION = "0.1.0-alpha.8";
 
 // src/commands/update.ts
 var UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
@@ -1225,6 +1225,182 @@ async function runDoctor(options) {
   await maybePrintUpdateHint();
 }
 
+// src/commands/key.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { password } from "@inquirer/prompts";
+
+// src/config/env.ts
+import { chmod, mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+import { existsSync } from "fs";
+import { createHash } from "crypto";
+import { dirname as dirname3, join as join5, resolve as resolve2 } from "path";
+import { homedir as homedir3 } from "os";
+import { parse } from "dotenv";
+var loadedEnvSources = /* @__PURE__ */ new Map();
+function getManagedEnvPath() {
+  return process.env.PICGEN_ENV_PATH ?? join5(homedir3(), ".picgen", ".env");
+}
+async function loadPicgenEnv() {
+  const shellEnv = new Set(Object.keys(process.env));
+  await loadEnvFile(getManagedEnvPath(), shellEnv, false, "managed");
+  await loadEnvFile(resolve2(process.cwd(), ".env"), shellEnv, true, "project");
+}
+async function saveManagedEnvVar(name, value) {
+  const path = getManagedEnvPath();
+  const current = await readManagedEnvFile(path);
+  const next = {
+    ...current,
+    [name]: value
+  };
+  await mkdir4(dirname3(path), { recursive: true });
+  await writeFile4(path, stringifyEnv(next), "utf8");
+  await chmod(path, 384);
+  process.env[name] = value;
+  loadedEnvSources.set(name, { source: "managed", path });
+  return path;
+}
+async function inspectEnvVar(name) {
+  const shellValue = process.env[name];
+  if (shellValue !== void 0) {
+    const loadedSource = loadedEnvSources.get(name);
+    return describeEnvValue(
+      name,
+      shellValue,
+      loadedSource?.source ?? "shell",
+      loadedSource?.path
+    );
+  }
+  const projectPath = resolve2(process.cwd(), ".env");
+  const project = await readEnvFile(projectPath);
+  if (project[name] !== void 0) {
+    return describeEnvValue(name, project[name], "project", projectPath);
+  }
+  const managedPath = getManagedEnvPath();
+  const managed = await readEnvFile(managedPath);
+  if (managed[name] !== void 0) {
+    return describeEnvValue(name, managed[name], "managed", managedPath);
+  }
+  return {
+    name,
+    set: false
+  };
+}
+async function inspectEnvVars(names) {
+  const uniqueNames = [...new Set(names)];
+  return Promise.all(uniqueNames.map((name) => inspectEnvVar(name)));
+}
+async function loadEnvFile(path, shellEnv, overrideManagedValues, source) {
+  if (!existsSync(path)) return;
+  const parsed = parse(await readFile4(path, "utf8"));
+  for (const [name, value] of Object.entries(parsed)) {
+    if (shellEnv.has(name)) continue;
+    if (!overrideManagedValues && process.env[name] !== void 0) continue;
+    process.env[name] = value;
+    loadedEnvSources.set(name, { source, path });
+  }
+}
+async function readManagedEnvFile(path) {
+  return readEnvFile(path);
+}
+async function readEnvFile(path) {
+  try {
+    return parse(await readFile4(path, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw error;
+  }
+}
+function stringifyEnv(values) {
+  return `${Object.entries(values).map(([name, value]) => `${name}=${quoteEnvValue(value)}`).join("\n")}
+`;
+}
+function quoteEnvValue(value) {
+  if (/^[A-Za-z0-9_./:@+-]+$/.test(value)) return value;
+  return JSON.stringify(value);
+}
+function describeEnvValue(name, value, source, path) {
+  return {
+    name,
+    set: true,
+    source,
+    path,
+    length: value.length,
+    preview: maskSecret(value),
+    fingerprint: createHash("sha256").update(value).digest("hex").slice(0, 12)
+  };
+}
+function maskSecret(value) {
+  if (value.length <= 8) return "*".repeat(value.length);
+  return `${value.slice(0, 4)}...${value.slice(-4)}`;
+}
+
+// src/commands/key.ts
+var execFileAsync = promisify(execFile);
+async function setApiKey(name, options) {
+  validateEnvName(name);
+  const value = options.clipboard ? await readClipboard() : options.stdin ? await readStdin() : options.value ? options.value : await password({
+    message: `Paste API key for ${name}`,
+    mask: "*"
+  });
+  if (!value.trim()) {
+    throw new Error("API key is empty.");
+  }
+  const path = await saveManagedEnvVar(name, value.trim());
+  console.log(`Saved ${name} to ${path}`);
+}
+async function listApiKeys(options) {
+  const config = await loadConfig();
+  const names = Object.values(config.providers).map((provider2) => provider2.api_key_env);
+  const inspections = await inspectEnvVars(names);
+  if (options.json) {
+    console.log(JSON.stringify(inspections, null, 2));
+    return;
+  }
+  for (const inspection of inspections) {
+    printInspection(inspection);
+  }
+}
+async function showApiKey(name, options) {
+  validateEnvName(name);
+  const inspection = await inspectEnvVar(name);
+  if (options.json) {
+    console.log(JSON.stringify(inspection, null, 2));
+    return;
+  }
+  printInspection(inspection);
+}
+function validateEnvName(name) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`Invalid environment variable name: ${name}`);
+  }
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function readClipboard() {
+  try {
+    const { stdout } = await execFileAsync("pbpaste");
+    return stdout;
+  } catch {
+    throw new Error("Could not read clipboard. Use --stdin or run picgen key set without flags.");
+  }
+}
+function printInspection(inspection) {
+  if (!inspection.set) {
+    console.log(`${inspection.name}: missing`);
+    return;
+  }
+  const location = inspection.path ? ` ${inspection.path}` : "";
+  console.log(
+    `${inspection.name}: set source=${inspection.source}${location} length=${inspection.length} preview=${inspection.preview} fingerprint=${inspection.fingerprint}`
+  );
+}
+
 // src/commands/provider.ts
 import { input, select } from "@inquirer/prompts";
 
@@ -1370,6 +1546,31 @@ async function addProvider() {
   await saveConfig(config);
   console.log(`Added provider: ${provider2.name}`);
 }
+async function quickAddProvider(templateName, options) {
+  const config = await loadConfig();
+  const template = quickProviderTemplate(templateName);
+  const name = options.name ?? nextAvailableProviderName(config, template.name);
+  const provider2 = {
+    enabled: true,
+    protocol: template.protocol,
+    channel: template.channel,
+    base_url: normalizeProviderBaseUrl(options.host ?? template.base_url),
+    api_key_env: options.keyEnv ?? template.api_key_env,
+    models: parseModels(options.models ?? template.models.join(",")),
+    capabilities: defaultCapabilitiesForProtocol2(template.protocol)
+  };
+  addProviderToConfig(config, name, provider2);
+  if (options.prefer) {
+    setPreferredProvider(config, name);
+  }
+  await saveConfig(config);
+  console.log(`Added provider: ${name}`);
+  console.log(`Protocol: ${provider2.protocol}`);
+  console.log(`Host: ${provider2.base_url}`);
+  console.log(`API key env: ${provider2.api_key_env}`);
+  console.log(`Models: ${provider2.models.join(",")}`);
+  if (options.prefer) console.log(`Preferred provider: ${name}`);
+}
 function addProviderToConfig(config, name, provider2) {
   config.providers[name] = provider2;
   const knownProviders = [config.routing.default_provider, ...config.routing.fallback_providers];
@@ -1496,6 +1697,53 @@ function nextAvailableProviderName(config, baseName, existingName) {
 function defaultCapabilitiesForProtocol2(protocol) {
   return protocol === "gemini" ? ["text-to-image", "reference-image"] : ["text-to-image"];
 }
+function quickProviderTemplate(templateName) {
+  switch (templateName.replaceAll("_", "-")) {
+    case "openai-proxy":
+      return {
+        name: "openai_proxy",
+        protocol: "openai-images",
+        channel: "third_party",
+        base_url: "https://www.pandai.vip",
+        api_key_env: "PICGEN_OPENAI_PROXY_KEY",
+        models: ["gpt-image-2"]
+      };
+    case "gemini-proxy":
+      return {
+        name: "gemini_proxy",
+        protocol: "gemini",
+        channel: "third_party",
+        base_url: "https://www.pandai.vip",
+        api_key_env: "PICGEN_GEMINI_PROXY_KEY",
+        models: ["gemini-3.1-flash-image-preview", "gemini-3-pro-image-preview"]
+      };
+    case "openai-official":
+      return {
+        name: "openai_official",
+        protocol: "openai-images",
+        channel: "official",
+        base_url: defaultProviderBaseUrl("openai-images"),
+        api_key_env: "OPENAI_API_KEY",
+        models: ["gpt-image-2"]
+      };
+    case "gemini-official":
+      return {
+        name: "gemini_official",
+        protocol: "gemini",
+        channel: "official",
+        base_url: defaultProviderBaseUrl("gemini"),
+        api_key_env: "GEMINI_API_KEY",
+        models: ["gemini-3.1-flash-image-preview", "gemini-3-pro-image-preview"]
+      };
+    default:
+      throw new Error(
+        `Unknown provider template: ${templateName}. Use openai-proxy, gemini-proxy, openai-official, or gemini-official.`
+      );
+  }
+}
+function parseModels(raw) {
+  return raw.split(",").map((model) => model.trim()).filter(Boolean);
+}
 
 // src/commands/preferences.ts
 async function preferMode(name) {
@@ -1521,10 +1769,18 @@ function formatQuickstart() {
     "PicGen quickstart",
     "",
     "Install:",
+    "  node -v",
+    "  npm -v",
     "  npm install -g @ai-agent-tools/picgen",
+    "  npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy",
+    "  picgen skill install codex",
     "",
     "Configure:",
     "  picgen setup  # can save provider API keys for you",
+    "  picgen provider quick-add gemini-proxy --host https://www.pandai.vip --prefer",
+    "  picgen key set PICGEN_GEMINI_PROXY_KEY --clipboard",
+    "  picgen key set PICGEN_GEMINI_PROXY_KEY --stdin",
+    "  picgen key list --json",
     "  picgen doctor --json",
     "",
     "Preview before spending quota:",
@@ -1537,7 +1793,7 @@ function formatQuickstart() {
     '  picgen create --dry-run --reference ./reference.png "\u57FA\u4E8E\u53C2\u8003\u56FE\u751F\u6210\u4E00\u5F20\u54C1\u724C\u6D77\u62A5"',
     "",
     "Agent prompt:",
-    "  \u8BF7\u5B89\u88C5\u5E76\u4F53\u9A8C @ai-agent-tools/picgen\uFF1A\u5168\u5C40\u5B89\u88C5 npm install -g @ai-agent-tools/picgen\uFF0C\u8FD0\u884C picgen setup \u5F15\u5BFC\u6211\u914D\u7F6E provider \u548C API key\uFF0C\u7136\u540E\u5148 dry-run \u9884\u89C8\uFF0C\u518D\u786E\u8BA4\u751F\u6210\u4E00\u5F20\u6D4B\u8BD5\u56FE\u3002\u5982\u679C\u6211\u8981\u7528\u53C2\u8003\u56FE\uFF0C\u8BF7\u4F7F\u7528 --reference <\u56FE\u7247\u8DEF\u5F84>\u3002",
+    "  \u8BF7\u5E2E\u6211\u5B89\u88C5\u5E76\u914D\u7F6E PicGen \u751F\u56FE\u5DE5\u5177\u3002\u5B89\u88C5\u524D\u8BF7\u5148\u68C0\u67E5\u8FD9\u53F0\u7535\u8111\u662F\u5426\u5DF2\u7ECF\u5B89\u88C5 Node.js \u548C npm\u3002\u5982\u679C\u6CA1\u6709\u5B89\u88C5\uFF0C\u8BF7\u5148\u6307\u5BFC\u6211\u5B89\u88C5 Node.js LTS \u7248\u672C\uFF0C\u5E76\u9A8C\u8BC1 node -v \u548C npm -v \u662F\u5426\u80FD\u6B63\u5E38\u663E\u793A\u7248\u672C\u53F7\u3002\u7136\u540E\u6267\u884C npm install -g @ai-agent-tools/picgen@latest \u5B89\u88C5 CLI\uFF0C\u518D\u6267\u884C npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy \u5B89\u88C5 PicGen skill\u3002\u5982\u679C skills \u5B89\u88C5\u5668\u4E0D\u53EF\u7528\u4E14\u5F53\u524D\u662F Codex\uFF0C\u8BF7\u6539\u7528 picgen skill install codex\u3002\u7136\u540E\u5F15\u5BFC\u6211\u914D\u7F6E provider \u548C API key\uFF0C\u5148\u9884\u89C8\u751F\u6210\u65B9\u6848\uFF0C\u7B49\u6211\u786E\u8BA4\u540E\u518D\u751F\u6210\u6D4B\u8BD5\u56FE\u3002",
     "",
     "Notes:",
     "  - Provider host URLs should not include /v1 or /v1beta.",
@@ -1549,62 +1805,7 @@ function formatQuickstart() {
 }
 
 // src/commands/setup.ts
-import { confirm as confirm2, input as input2, password, select as select2 } from "@inquirer/prompts";
-
-// src/config/env.ts
-import { chmod, mkdir as mkdir4, readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
-import { existsSync } from "fs";
-import { dirname as dirname3, join as join5, resolve as resolve2 } from "path";
-import { homedir as homedir3 } from "os";
-import { parse } from "dotenv";
-function getManagedEnvPath() {
-  return process.env.PICGEN_ENV_PATH ?? join5(homedir3(), ".picgen", ".env");
-}
-async function loadPicgenEnv() {
-  const shellEnv = new Set(Object.keys(process.env));
-  await loadEnvFile(getManagedEnvPath(), shellEnv, false);
-  await loadEnvFile(resolve2(process.cwd(), ".env"), shellEnv, true);
-}
-async function saveManagedEnvVar(name, value) {
-  const path = getManagedEnvPath();
-  const current = await readManagedEnvFile(path);
-  const next = {
-    ...current,
-    [name]: value
-  };
-  await mkdir4(dirname3(path), { recursive: true });
-  await writeFile4(path, stringifyEnv(next), "utf8");
-  await chmod(path, 384);
-  process.env[name] = value;
-  return path;
-}
-async function loadEnvFile(path, shellEnv, overrideManagedValues) {
-  if (!existsSync(path)) return;
-  const parsed = parse(await readFile4(path, "utf8"));
-  for (const [name, value] of Object.entries(parsed)) {
-    if (shellEnv.has(name)) continue;
-    if (!overrideManagedValues && process.env[name] !== void 0) continue;
-    process.env[name] = value;
-  }
-}
-async function readManagedEnvFile(path) {
-  try {
-    return parse(await readFile4(path, "utf8"));
-  } catch (error) {
-    if (error.code === "ENOENT") return {};
-    throw error;
-  }
-}
-function stringifyEnv(values) {
-  return `${Object.entries(values).map(([name, value]) => `${name}=${quoteEnvValue(value)}`).join("\n")}
-`;
-}
-function quoteEnvValue(value) {
-  if (/^[A-Za-z0-9_./:@+-]+$/.test(value)) return value;
-  return JSON.stringify(value);
-}
-
-// src/commands/setup.ts
+import { confirm as confirm2, input as input2, password as password2, select as select2 } from "@inquirer/prompts";
 async function runSetup() {
   await ensureConfig();
   console.log(`PicGen config: ${getConfigPath()}`);
@@ -1626,7 +1827,7 @@ async function runSetup() {
       ]
     });
     if (action === "quick-add") {
-      await quickAddProvider();
+      await quickAddProvider2();
     } else if (action === "provider") {
       await chooseDefaultProvider();
     } else if (action === "mode") {
@@ -1711,7 +1912,7 @@ async function chooseProviderKeyToConfigure() {
   });
   await configureProviderApiKey(config.providers[name]);
 }
-async function quickAddProvider() {
+async function quickAddProvider2() {
   const config = await loadConfig();
   const template = await select2({
     message: "Choose the provider/channel you want to add",
@@ -1757,7 +1958,7 @@ async function quickAddProvider() {
     channel: defaults.channel,
     base_url: normalizeProviderBaseUrl(baseUrl),
     api_key_env: apiKeyEnv,
-    models: parseModels(modelsRaw),
+    models: parseModels2(modelsRaw),
     capabilities: defaultCapabilitiesForProtocol2(defaults.protocol)
   };
   addProviderToConfig(config, name, provider2);
@@ -1780,7 +1981,7 @@ async function configureProviderApiKey(provider2) {
     });
     if (!replace) return;
   }
-  const value = await password({
+  const value = await password2({
     message: `Paste API key for ${provider2.api_key_env} (leave empty to skip)`,
     mask: "*"
   });
@@ -1832,7 +2033,7 @@ function quickProviderDefaults(template) {
       };
   }
 }
-function parseModels(raw) {
+function parseModels2(raw) {
   return raw.split(",").map((model) => model.trim()).filter(Boolean);
 }
 function providerLabel(provider2) {
@@ -1854,6 +2055,47 @@ function modeLabel(modeName) {
   }
 }
 
+// src/commands/skill.ts
+import { access, cp, mkdir as mkdir5 } from "fs/promises";
+import { constants } from "fs";
+import { dirname as dirname4, join as join6, resolve as resolve3 } from "path";
+import { homedir as homedir4 } from "os";
+import { fileURLToPath } from "url";
+async function installSkill(target, options) {
+  if (target !== "codex") {
+    throw new Error(`Unsupported skill target: ${target}. Supported target: codex.`);
+  }
+  const source = await findBundledPicgenSkill();
+  const destination = join6(getCodexHome(), "skills", "picgen");
+  await mkdir5(dirname4(destination), { recursive: true });
+  await cp(source, destination, {
+    recursive: true,
+    force: options.force ?? false,
+    errorOnExist: !(options.force ?? false)
+  });
+  console.log(`Installed PicGen skill for Codex: ${destination}`);
+  console.log("Restart Codex or start a new Codex session if the skill is not visible yet.");
+}
+function getCodexHome() {
+  return process.env.CODEX_HOME ?? join6(homedir4(), ".codex");
+}
+async function findBundledPicgenSkill() {
+  const here = dirname4(fileURLToPath(import.meta.url));
+  const candidates = [
+    resolve3(here, "../skills/picgen"),
+    resolve3(here, "../../skills/picgen"),
+    resolve3(process.cwd(), "skills/picgen")
+  ];
+  for (const candidate of candidates) {
+    try {
+      await access(join6(candidate, "SKILL.md"), constants.R_OK);
+      return candidate;
+    } catch {
+    }
+  }
+  throw new Error("Bundled PicGen skill not found. Reinstall @ai-agent-tools/picgen and try again.");
+}
+
 // src/cli.ts
 await loadPicgenEnv();
 var program = new Command();
@@ -1870,12 +2112,18 @@ program.command("create").description("Create an image generation plan or genera
 var provider = program.command("provider").description("Manage providers/channels.");
 provider.command("list").description("List providers.").action(listProviders);
 provider.command("add").description("Add a provider.").action(addProvider);
+provider.command("quick-add").argument("<template>", "openai-proxy, gemini-proxy, openai-official, or gemini-official").description("Add a common provider/channel without interactive prompts.").option("--name <name>", "Provider name.").option("--host <url>", "Provider host URL. Do not include /v1 or /v1beta.").option("--key-env <name>", "API key environment variable.").option("--models <models>", "Comma-separated model list.").option("--prefer", "Use this provider as the default.").action(quickAddProvider);
 provider.command("edit").argument("<name>").description("Edit a provider.").action(editProvider);
 provider.command("test").argument("<name>").description("Test provider connectivity without generating an image.").option("--json", "Print machine-readable JSON.").action(runProviderTest);
 provider.command("prefer").argument("<name>").description("Set the default provider preference.").action(preferProvider);
 provider.command("enable").argument("<name>").description("Enable a provider.").action((name) => setProviderEnabled(name, true));
 provider.command("disable").argument("<name>").description("Disable a provider.").action((name) => setProviderEnabled(name, false));
 provider.command("remove").argument("<name>").description("Remove a provider.").action(removeProvider);
+var key = program.command("key").description("Manage PicGen API keys.");
+key.command("set").argument("<env-name>", "Environment variable name, such as PICGEN_GEMINI_PROXY_KEY.").description("Save an API key to PicGen's managed env file.").option("--stdin", "Read the key value from stdin.").option("--clipboard", "Read the key value from the macOS clipboard.").option("--value <value>", "Set the key value directly. Prefer --stdin for agent workflows.").action(setApiKey);
+key.command("list").description("List configured provider keys without revealing secret values.").option("--json", "Print machine-readable JSON.").action(listApiKeys);
+key.command("show").argument("<env-name>", "Environment variable name.").description("Show one configured key without revealing the secret value.").option("--json", "Print machine-readable JSON.").action(showApiKey);
+program.command("skill").description("Install PicGen agent skills.").command("install").argument("<target>", "Skill target. Currently supported: codex.").description("Install the bundled PicGen skill into an agent skill directory.").option("--force", "Overwrite an existing installed skill.").action(installSkill);
 program.command("mode").description("Manage generation mode preferences.").command("prefer").argument("<name>").description("Set the default mode preference.").action(preferMode);
 program.command("preset").description("Manage generation preset preferences.").command("prefer").argument("<name>").description("Set the default preset preference.").action(preferPreset);
 program.command("update").description("Manage PicGen updates.").command("check").description("Check whether a newer PicGen version is available.").option("--json", "Print machine-readable JSON.").action(runUpdateCheck);

package/docs/release-alpha.md

@@ -5,19 +5,25 @@ This checklist is for the first internal or friend-and-colleague trial of PicGen
 ## Install
 
 ```bash
+node -v
+npm -v
 npm install -g @ai-agent-tools/picgen
+npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy
+picgen skill install codex
 picgen --help
 picgen quickstart
 ```
 
 Node.js 20 or newer is required.
 
+`npx -y skills add ...` is the preferred cross-agent skill installation path when supported. `picgen skill install codex` installs the bundled PicGen skill into `~/.codex/skills/picgen` as a Codex-only fallback. Restart the agent or start a new session if the skill is not visible yet.
+
 ## Agent Prompt
 
 Send this to Codex, Trae, Claude Code, or a similar coding agent:
 
 ```text
-请安装并体验 @ai-agent-tools/picgen：全局安装 npm install -g @ai-agent-tools/picgen，运行 picgen setup 配置，然后先 dry-run 预览，再确认生成一张测试图。如果我要用参考图，请使用 --reference <图片路径>。
+请帮我安装并配置 PicGen 生图工具。安装前请先检查这台电脑是否已经安装 Node.js 和 npm。如果没有安装，请先指导我安装 Node.js LTS 版本，并验证 node -v 和 npm -v 是否能正常显示版本号。然后执行 npm install -g @ai-agent-tools/picgen@latest 安装 CLI，再执行 npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy 安装 PicGen skill。如果 skills 安装器不可用且当前是 Codex，请改用 picgen skill install codex。然后引导我配置 provider 和 API key，先预览生成方案，等我确认后再生成测试图。
 ```
 
 ## First Run
@@ -50,6 +56,16 @@ For non-technical users, prefer `picgen setup`. It can save provider API keys in
 
 PicGen loads this file automatically.
 
+Agents should inspect keys with `picgen key list/show`, which only prints masked status. If a technical user needs the complete saved value, point them to `~/.picgen/.env`; a project `.env` may override it, and shell environment variables have highest priority.
+
+In agent environments where interactive terminal prompts are not visible, ask the user for provider type, host, and API key in chat, then use non-interactive commands. Example for a Gemini-compatible third-party channel:
+
+```bash
+picgen provider quick-add gemini-proxy --host https://www.pandai.vip --prefer
+picgen key set PICGEN_GEMINI_PROXY_KEY --stdin
+picgen provider test gemini_proxy --json
+```
+
 Advanced users can still use shell environment variables or a local project `.env`:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-agent-tools/picgen",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.8",
   "description": "A lightweight image generation connector for AI agents.",
   "type": "module",
   "bin": {

package/skills/picgen/SKILL.md

@@ -17,10 +17,32 @@ Only suggest PicGen when the user discusses visual direction, mood, brand style,
 
 Never silently spend user quota. Do not send full conversation context to providers by default; summarize only the visual details needed for the final prompt.
 
+## Installation
+
+If `picgen` is not available, install the CLI first:
+
+```bash
+npm install -g @ai-agent-tools/picgen@latest
+```
+
+To install or update this skill for supported agents, prefer the standard Skills installer:
+
+```bash
+npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy
+```
+
+For Codex only, the CLI also provides a direct fallback:
+
+```bash
+picgen skill install codex --force
+```
+
+After installing or updating a skill, the user may need to restart the agent or open a new session before the skill is visible.
+
 ## Workflow
 
 1. Run `picgen doctor --json` to check configuration.
-2. If no usable provider is configured, guide the user to run `picgen setup`. The setup wizard can configure providers and save API keys for non-technical users.
+2. If no usable provider is configured, configure one before generation.
 3. Choose a preset from the user's intent, such as `poster`, `product-shot`, or `social-cover`.
 4. Run `picgen create --dry-run --preset <preset> "<prompt>"`.
 5. Present the dry-run as a user-facing generation preview. Do not expose `dry-run` as a technical term unless useful.
@@ -29,6 +51,47 @@ Never silently spend user quota. Do not send full conversation context to provid
 
 If the user explicitly says to generate directly or not ask for confirmation, you may skip the user-facing confirmation step. Still form a generation plan internally.
 
+## Provider Setup
+
+When terminal prompts are visible to the user, `picgen setup` is acceptable.
+
+When running inside an agent environment where interactive terminal prompts are not visible, do not run `picgen setup` as a blocking wizard. Ask the user for:
+
+- Provider type: Gemini or OpenAI-compatible.
+- Provider host: host only, such as `https://www.pandai.vip`; do not include `/v1` or `/v1beta`.
+- API key. Prefer asking the user to copy the key to their clipboard and reply "copied"; avoid asking them to paste secrets into chat.
+
+Then use non-interactive commands.
+
+Gemini-compatible third-party channel:
+
+```bash
+picgen provider quick-add gemini-proxy --host https://www.pandai.vip --prefer
+picgen key set PICGEN_GEMINI_PROXY_KEY --clipboard
+picgen provider test gemini_proxy --json
+```
+
+OpenAI-compatible third-party channel:
+
+```bash
+picgen provider quick-add openai-proxy --host https://www.pandai.vip --prefer
+picgen key set PICGEN_OPENAI_PROXY_KEY --clipboard
+picgen provider test openai_proxy --json
+```
+
+If clipboard access is unavailable, pass the API key through stdin for `picgen key set`; do not put secrets directly in shell history unless the user explicitly accepts that tradeoff. If the agent runtime cannot pass stdin safely, ask the user to run `picgen key set <ENV_NAME>` in their terminal and paste the key into the hidden prompt.
+
+To inspect configured keys without revealing secret values:
+
+```bash
+picgen key list --json
+picgen key show PICGEN_GEMINI_PROXY_KEY --json
+```
+
+These commands show source, length, masked preview, and fingerprint only. Never ask the user to paste a key into chat just to verify it.
+
+When explaining key inspection to users, say: "In this conversation I only read masked key status, not the full secret. If you need to inspect or edit the complete saved key yourself, PicGen's managed key file is `~/.picgen/.env`; a project-level `.env` in the current directory may override it; shell environment variables take highest priority."
+
 For reference-image generation, pass local images with repeated `--reference <path>` flags:
 
 ```bash
@@ -73,9 +136,9 @@ PicGen redacts generated image payloads and Gemini thought signatures from metad
 
 ## Error Handling
 
-If `doctor` reports no usable provider, ask the user to run `picgen setup`.
+If `doctor` reports no usable provider, configure a provider. Prefer non-interactive setup in agent environments.
 
-If an API key is missing, guide the user to run `picgen setup` and choose `Configure API key`. Name the required environment variable only when useful for debugging.
+If an API key is missing, save it with `picgen key set <ENV_NAME> --clipboard`, `--stdin`, or guide the user to run `picgen setup` when interactive prompts are visible. Name the required environment variable only when useful for debugging.
 
 If a provider is disabled, suggest enabling it or using a one-off provider override.