@ai-agent-tools/picgen 0.1.0-alpha.1 → 0.1.0-alpha.10

package/README.md

@@ -10,6 +10,7 @@ Alpha goals:
 - Gemini reference-image generation
 - `provider + preset + routing` configuration
 - `picgen setup`, `picgen doctor`, `picgen create --dry-run`
+- Local web interface with settings, generation, and history
 - Local Codex skill instructions
 
 ## Development
@@ -26,32 +27,46 @@ 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
+picgen open
 ```
 
+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 生图工具。请先阅读并按这个指南执行：https://raw.githubusercontent.com/ai-agent-tools/picgen/refs/heads/main/docs/agent-install.md 。你负责判断是否在本机持久环境、安装 CLI 和 skill、引导我配置 provider/API key，并先预览生成方案，等我确认后再生成测试图。不要让我理解命令细节，也不要让我把 API key 发到聊天里。
 ```
 
-For first-user rollout, see [docs/release-alpha.md](./docs/release-alpha.md).
+For agent-assisted installation, see [docs/agent-install.md](./docs/agent-install.md). For first-user rollout, see [docs/release-alpha.md](./docs/release-alpha.md).
 
 ## Commands
 
 ```bash
 picgen setup
 picgen quickstart
+picgen open
+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
@@ -66,6 +81,8 @@ Quick-add setup asks only for the essentials: provider name, host URL, API key e
 
 Real `picgen create` calls ask for confirmation before contacting a provider. Use `--yes` only when you want to skip that CLI confirmation.
 
+`picgen open` starts a local web interface at `127.0.0.1`, defaulting to port `8188`. It is a foreground local server: keep the terminal open while using the page, and press Ctrl+C to close it. The page can configure multiple providers, save API keys to PicGen's managed env file, preview generation plans, generate images, and browse saved history under `outputs/picgen`.
+
 `--reference <path>` can be repeated to pass local reference images. Alpha supports reference images through the Gemini adapter. The OpenAI-compatible `/v1/images/generations` adapter does not support reference images yet; use a Gemini provider for reference-image generation.
 
 Gemini generation requests ask for image-only responses with `responseModalities: ["IMAGE"]`. Provider health checks still use a text-only request so they can verify host, key, model, and endpoint readiness without triggering image generation.
@@ -91,6 +108,20 @@ OPENAI_API_KEY=...
 GEMINI_API_KEY=...
 ```
 
+For non-technical users, `picgen setup` can save API keys for you in:
+
+```text
+~/.picgen/.env
+```
+
+PicGen loads this managed env file automatically. Shell environment variables take priority, and a project `.env` can override the managed file for local testing.
+
+Each provider should have its own `api_key_env` value. When adding another provider of the same type, PicGen assigns a new key name by default, such as `PICGEN_GEMINI_PROXY_2_KEY`, so multiple channels do not overwrite each other's API keys.
+
+Older configs that reused the same `api_key_env` across multiple providers are migrated automatically when PicGen loads the config. PicGen keeps the first provider unchanged, assigns unique key names to the later providers, and copies the existing key value into the managed env file when the value is available.
+
+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
@@ -101,6 +132,12 @@ Provider `base_url` values should be host-only. Do not include `/v1` or `/v1beta
 
 Providers may optionally set `test_model` in `~/.picgen/config.yaml` when health checks should use a lightweight model instead of the first generation model.
 
+Generation requests use adaptive provider timeouts: fast draft requests allow 120s, balanced requests allow 180s, and high quality or large requests allow 300s. If a third-party channel is slower, override it with `PICGEN_PROVIDER_TIMEOUT_MS`:
+
+```bash
+PICGEN_PROVIDER_TIMEOUT_MS=450000 picgen create --yes --preset poster "一张产品发布会主视觉"
+```
+
 Providers expose capabilities such as `text-to-image` and `reference-image`. Old configs that omit capabilities are upgraded in memory from the provider protocol: Gemini supports both text and reference-image generation, while OpenAI-compatible `/v1/images/generations` supports text-to-image only.
 
 Generated image data and provider-only fields such as base64 image payloads and Gemini thought signatures are redacted from metadata. PicGen keeps the generated assets as local image files and keeps stdout compact for agent workflows.