@ai-agent-tools/picgen 0.1.0-alpha.7 → 0.1.0-alpha.9

package/README.md

@@ -54,14 +54,16 @@ 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 "一张产品发布会主视觉"
-picgen create --yes "一张产品发布会主视觉"
+picgen create --dry-run --preset fast-draft "一张简洁的 PicGen 测试图"
+picgen create --yes --preset fast-draft "一张简洁的 PicGen 测试图"
 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
@@ -109,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.7";
+var VERSION = "0.1.0-alpha.9";
 
 // src/commands/update.ts
 var UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
@@ -1226,21 +1226,25 @@ async function runDoctor(options) {
 }
 
 // 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);
-  await loadEnvFile(resolve2(process.cwd(), ".env"), shellEnv, true);
+  await loadEnvFile(getManagedEnvPath(), shellEnv, false, "managed");
+  await loadEnvFile(resolve2(process.cwd(), ".env"), shellEnv, true, "project");
 }
 async function saveManagedEnvVar(name, value) {
   const path = getManagedEnvPath();
@@ -1253,18 +1257,53 @@ async function saveManagedEnvVar(name, value) {
   await writeFile4(path, stringifyEnv(next), "utf8");
   await chmod(path, 384);
   process.env[name] = value;
+  loadedEnvSources.set(name, { source: "managed", path });
   return path;
 }
-async function loadEnvFile(path, shellEnv, overrideManagedValues) {
+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) {
@@ -1280,11 +1319,27 @@ 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 <= 11) return "*".repeat(value.length);
+  return `${value.slice(0, 7)}...${value.slice(-4)}`;
+}
 
 // src/commands/key.ts
+var execFileAsync = promisify(execFile);
 async function setApiKey(name, options) {
   validateEnvName(name);
-  const value = options.stdin ? await readStdin() : options.value ? options.value : await password({
+  const value = options.clipboard ? await readClipboard() : options.stdin ? await readStdin() : options.value ? options.value : await password({
     message: `Paste API key for ${name}`,
     mask: "*"
   });
@@ -1294,6 +1349,27 @@ async function setApiKey(name, options) {
   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}`);
@@ -1306,6 +1382,24 @@ async function readStdin() {
   }
   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";
@@ -1684,14 +1778,16 @@ function formatQuickstart() {
     "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:",
-    '  picgen create --dry-run "\u4E00\u5F20\u6781\u7B80\u79D1\u6280\u611F\u4EA7\u54C1\u6D77\u62A5"',
+    '  picgen create --dry-run --preset fast-draft "\u4E00\u5F20\u7B80\u6D01\u7684 PicGen \u6D4B\u8BD5\u56FE"',
     "",
     "Generate after confirmation:",
-    '  picgen create --yes "\u4E00\u5F20\u6781\u7B80\u79D1\u6280\u611F\u4EA7\u54C1\u6D77\u62A5"',
+    '  picgen create --yes --preset fast-draft "\u4E00\u5F20\u7B80\u6D01\u7684 PicGen \u6D4B\u8BD5\u56FE"',
     "",
     "Use a reference image:",
     '  picgen create --dry-run --reference ./reference.png "\u57FA\u4E8E\u53C2\u8003\u56FE\u751F\u6210\u4E00\u5F20\u54C1\u724C\u6D77\u62A5"',
@@ -2023,7 +2119,10 @@ provider.command("prefer").argument("<name>").description("Set the default provi
 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);
-program.command("key").description("Manage PicGen API keys.").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("--value <value>", "Set the key value directly. Prefer --stdin for agent workflows.").action(setApiKey);
+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);

package/docs/release-alpha.md

@@ -56,6 +56,8 @@ 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
@@ -92,7 +94,7 @@ picgen update check
 Always start with dry-run:
 
 ```bash
-picgen create --dry-run "一张极简科技感产品海报"
+picgen create --dry-run --preset fast-draft "一张简洁的 PicGen 测试图"
 ```
 
 Dry-run does not call providers and does not spend quota.

package/package.json

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

package/skills/picgen/SKILL.md

@@ -59,7 +59,7 @@ When running inside an agent environment where interactive terminal prompts are
 
 - Provider type: Gemini or OpenAI-compatible.
 - Provider host: host only, such as `https://www.pandai.vip`; do not include `/v1` or `/v1beta`.
-- API key.
+- 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.
 
@@ -67,7 +67,7 @@ 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 key set PICGEN_GEMINI_PROXY_KEY --clipboard
 picgen provider test gemini_proxy --json
 ```
 
@@ -75,11 +75,22 @@ 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 --stdin
+picgen key set PICGEN_OPENAI_PROXY_KEY --clipboard
 picgen provider test openai_proxy --json
 ```
 
-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.
+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:
 
@@ -92,6 +103,36 @@ Use Gemini providers for reference-image generation in Alpha. The OpenAI-compati
 
 PicGen routes by provider capabilities. When reference images are provided, agents may omit `--provider` and let PicGen select a provider that supports `reference-image`, unless the user explicitly requested a provider.
 
+## First Smoke Test
+
+After configuring a provider, run the first test generation with a low-cost, fast, one-image plan. Do not use `poster`, `product-shot`, `social-cover`, premium modes, large sizes, or multi-image presets for initial verification.
+
+For Gemini providers, prefer the flash image model for the first test:
+
+```bash
+picgen create --dry-run --provider gemini_proxy --preset fast-draft --model gemini-3.1-flash-image-preview "一张简洁的 PicGen 测试图，白色背景，少量蓝绿色科技感点缀"
+picgen create --yes --provider gemini_proxy --preset fast-draft --model gemini-3.1-flash-image-preview "一张简洁的 PicGen 测试图，白色背景，少量蓝绿色科技感点缀"
+```
+
+For OpenAI-compatible providers:
+
+```bash
+picgen create --dry-run --provider openai_proxy --preset fast-draft "一张简洁的 PicGen 测试图，白色背景，少量蓝绿色科技感点缀"
+picgen create --yes --provider openai_proxy --preset fast-draft "一张简洁的 PicGen 测试图，白色背景，少量蓝绿色科技感点缀"
+```
+
+Present the dry-run preview and ask for confirmation before the real generation unless the user explicitly asked to generate immediately. The first smoke test should generate one image.
+
+## After Provider Success
+
+After one provider is configured and the first smoke test succeeds, tell the user the provider is ready and ask whether they want to add another channel as a fallback. Example:
+
+```text
+Gemini 渠道已经配置并测试成功。你还可以继续添加另一个渠道作为备用，例如 OpenAI-compatible。要继续添加吗？
+```
+
+If the user says yes, repeat provider setup and smoke testing for the next channel. If the user says no, stop setup and tell them PicGen is ready to use.
+
 ## Preferences and Overrides
 
 Treat `picgen create` flags as one-off overrides. They must not change user preferences:
@@ -127,7 +168,7 @@ PicGen redacts generated image payloads and Gemini thought signatures from metad
 
 If `doctor` reports no usable provider, configure a provider. Prefer non-interactive setup in agent environments.
 
-If an API key is missing, save it with `picgen key set <ENV_NAME> --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 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.
 
@@ -146,14 +187,14 @@ Explicit:
 Confirmation:
 
 ```text
-我可以用 PicGen 基于当前方案生成一版主视觉。要我现在生成吗？默认用 poster 预设，出 2 张。
+我可以先用 PicGen 做一次轻量测试生成，默认只出 1 张，确认工具和渠道都可用。要我现在开始吗？
 ```
 
 Generation preview:
 
 ```text
 生成预览：
-我将使用 OpenAI 官方渠道生成 2 张发布会海报，比例 3:4，保存到本地。
+我将使用当前渠道生成 1 张轻量测试图，保存到本地。
 
 确认后开始生成。
 ```