wov-api/AGENTS.md

WOV API

本仓库是 WOV 平台后端，负责节点注册、工作流编排、任务调度和用户 API。

职责

• 维护 SQLite 节点注册表和节点实例状态。
• 通过 NodeManager 启动、复用和回收独立节点进程。
• 提供管理端 API：注册节点、查看实例、停止实例。
• 后续增加工作流 DAG、WorkflowRun、用户上传和产物下载。

运行

uv sync
uv run uvicorn app.main:app --reload

uv sync 默认会安装 [dependency-groups] dev，包括 pytest、pytest-cov 和 httpx。

如果 8000 端口被占用或 Windows 提示 WinError 10013，先检查监听端口，然后改用其他端口：

Get-NetTCPConnection -LocalPort 8000 -State Listen
uv run uvicorn app.main:app --reload --port 8001

不变量

• 节点生命周期只能由 NodeManager 管理，API 不直接启动或杀死节点。
• 节点进程不共享 API 内存，中间产物通过 URI 落盘。
• 后续切换 PostgreSQL、对象存储和分布式队列时，不能破坏这些边界。

环境

• Python 环境统一使用 uv 管理，不直接使用 pip 修改依赖。
• 测试必须达到 100% 行覆盖率，且只能通过调用真实代码路径覆盖。
• 行覆盖率不包含外部端口占用/权限问题；真实网络启动由 uvicorn 冒烟测试单独覆盖。