Publish current ComfyUI O1Key code baseline

Replace the prior release tree with the current plugin, frontend, tests, and documentation. Document retired node IDs and the public Gitea update source.
2026-09-24 19:56:48 +08:00
parent 3e337722ab
commit ba920f2b66
183 changed files with 49496 additions and 9934 deletions
@@ -0,0 +1,59 @@
+# Configuration
+
+## Source of truth
+
+Runtime credential and route behavior is implemented in `utils/config.py`. Update this document and `README.md` whenever supported keys or precedence changes.
+
+## Configuration file
+
+The plugin stores settings in a UTF-8 `.config` file at the plugin root:
+
+```text
+O1KEY_API_KEY=replace-with-your-key
+O1KEY_NETWORK_ROUTE=全球加速
+```
+
+Use the ComfyUI sidebar's「令牌管理」window to write settings atomically. `.config` is ignored by Git and must never be copied into docs, fixtures, logs, screenshots, or issue reports.
+
+Supported file keys:
+
+| Key | Purpose |
+| --- | --- |
+| `O1KEY_API_KEY` | Authentication token used by provider clients |
+| `O1KEY_NETWORK_ROUTE` | Global named route selected by the settings UI |
+| `O1KEY_API_BASE_URL` | Custom synchronous fallback base URL |
+| `O1KEY_ASYNC_API_BASE_URL` | Custom asynchronous fallback base URL |
+
+Omni Flash reads `O1KEY_API_KEY` through the same configuration helper as image generation. Connected media uploads and generation use the selected O1Key network route; the key never becomes a workflow widget value.
+
+Named routes and defaults are defined in `utils/config.py`; do not duplicate endpoint constants in nodes.
+
+## Resolution behavior
+
+- A recognized global named route resolves to its configured endpoint.
+- Direct base-URL helpers fall back to the custom URL and then the built-in default when no named route is stored.
+- Route-aware callers using `get_base_url_by_route()` use the explicit route when supplied, otherwise the global route.
+- Clients that cache configuration should key that cache with `get_runtime_config_signature()` so UI changes take effect without restarting.
+
+## Diagnostic environment flags
+
+Environment variables are currently used for logging behavior, not as the primary credential store:
+
+| Variable | Effect |
+| --- | --- |
+| `O1KEY_DEBUG_LOG=1` | Enables Nano Banana debug logging |
+| `O1KEY_VERBOSE_LOG=1` | Enables verbose transport logging |
+| `O1KEY_RESPONSE_LOG=1` | Enables response logging where supported |
+
+Verbose response logging can expose sensitive metadata, so keep it disabled by default and never enable it in committed test configuration. Complete base64 media payloads are always redacted from logs, including when verbose logging is enabled.
+
+## Security rules
+
+- Mask API keys in UI responses and error reports.
+- Do not serialize credentials into ComfyUI workflows.
+- Do not log authorization headers, signed URLs, or complete user media payloads.
+- Keep `.config` during plugin upgrades and exclude it from cleanup scripts except for explicit user-requested credential removal.
+
+## Runtime history storage
+
+Completed, failed, and cancelled panel-image jobs are indexed at `<ComfyUI user directory>/o1key/image_job_history.json`. This is runtime UI state rather than configuration and is capped at 200 records. It contains only batch and node IDs, terminal state, bounded counts/timestamps/error summaries, and sanitized ComfyUI image descriptors. Prompts, reference manifests, local absolute save paths, credentials, Base64 payloads, and signed URLs must never enter this file. Native single-item history deletion and clear-history actions update the same index atomically.