comfyui_o1key/AGENTS.md

AGENTS.md

Project mission

Maintain comfyui_o1key as a reliable ComfyUI custom-node package. Changes must preserve saved-workflow compatibility, keep credentials out of workflows and logs, and leave the plugin importable in the bundled Windows environment.

Read first

• Start with docs/README.md and open only the document relevant to the task.
• Treat __init__.py as the runtime integration point and canonical node registry.
• Treat nodes/__init__.py as the package export list, not a second independent registry.
• WEB_DIRECTORY = "./web" means every JavaScript file under web/ is runtime code.
• Preserve unrelated working-tree changes. Do not commit unless the user explicitly asks.

Repository map

• __init__.py: node mappings, display names, HTTP routes, runtime hooks, and WEB_DIRECTORY.
• prestartup_script.py: startup policy applied before normal plugin import.
• nodes/: ComfyUI schemas and node execution adapters.
• clients/: provider-specific HTTP clients and response parsing.
• utils/: shared configuration, media conversion, retry, polling, upload, and job helpers.
• web/js/: auto-loaded ComfyUI frontend extensions.
• cases/: runtime case-library JSON files; do not treat as disposable fixtures.
• tests/: offline tests; use the isolated runner.
• docs/: architecture, configuration, development workflow, decisions, and maintenance history.

Non-negotiable invariants

• Never expose .config, API keys, authorization headers, full base64 payloads, or signed temporary URLs in docs, tests, fixtures, or logs.
• Do not rename a released node ID or a NODE_CLASS_MAPPINGS key without a workflow migration and an explicit compatibility decision.
• When adding or removing a node, update its module, nodes/__init__.py, root mappings, display mappings, relevant frontend migrations, tests, and docs together.
• Keep API transport in clients/ or utils/; node classes should focus on schema validation and orchestration.
• Keep tests offline. Mock network traffic, downloads, ComfyUI services, and user configuration.
• Do not add generated caches, screenshots, browser state, local AI-tool settings, ad-hoc reports, or real output media to the repository.
• Use UTF-8 text and preserve the repository line-ending policy in .gitattributes.

Change workflow

1. Inspect git status --short, the relevant docs, and direct references with rg.
2. Identify the runtime boundary: backend node/client/util, server route, frontend extension, or compatibility migration.
3. Make the smallest coherent change across that boundary.
4. Add or update an offline regression test.
5. Run the relevant test file, then tests/run_all.py for cross-cutting changes.
6. Run an import smoke test when registration, imports, requirements, or startup behavior changes.
7. Update docs/ when behavior, architecture, configuration, or maintenance expectations change.

Validation commands

Run from the plugin root in the portable Windows layout:

..\..\..\python_embeded\python.exe tests\run_all.py
..\..\..\python_embeded\python.exe -m compileall -q __init__.py prestartup_script.py models_config.py clients nodes utils tests
..\..\..\python_embeded\python.exe -c "import sys; sys.path.insert(0, '..'); import comfyui_o1key; print(len(comfyui_o1key.NODE_CLASS_MAPPINGS))"
git diff --check

For a single Python test:

..\..\..\python_embeded\python.exe tests\test_http2_client.py

For the frontend test:

node tests\test_o1key_image_generator_frontend.mjs

Documentation contract

• README.md is user-facing installation and usage documentation.
• docs/README.md is the maintainer and agent entry point.
• Architecture changes belong in docs/architecture.md.
• Configuration changes belong in docs/configuration.md and must match utils/config.py.
• Reusable implementation procedures belong in docs/development.md or docs/testing.md.
• Significant irreversible or compatibility-sensitive choices require an ADR under docs/decisions/.
• One-off cleanup history belongs under docs/maintenance/, not in the repository root.

Scoped guidance

Read the closest nested instructions before editing specialized areas:

• nodes/AGENTS.md
• web/AGENTS.md
• tests/AGENTS.md