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.
This commit is contained in:
Jony
@@ -0,0 +1,86 @@
|
||||
# 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:
|
||||
|
||||
```powershell
|
||||
..\..\..\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:
|
||||
|
||||
```powershell
|
||||
..\..\..\python_embeded\python.exe tests\test_http2_client.py
|
||||
```
|
||||
|
||||
For the frontend test:
|
||||
|
||||
```powershell
|
||||
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`
|
||||
Reference in New Issue
Block a user