OpenAPI 边界

OpenAPI 是 LightFlow 的网络控制面。它允许未来 UI、CLI、agent 和非 Linux client 访问 Linux-hosted LightFlow server。

当前 contract 位于：


openapi/lightflow.yaml

设计目标

API 应该暴露可检查的项目状态，而不是暴露内部 Rust API。

Client 不应该解析 Rust asset source。它们应该请求 backend，由 backend 负责：

asset scanning
metadata extraction
workflow parsing
reference validation
run planning
XDG state access
CortexFS submit and refresh

Asset endpoints


GET /workflows
GET /nodes
GET /compositions
GET /models

这些 endpoint 返回 AssetRecord 列表，包含 metadata、source path 和是否 built-in。

Run endpoints


POST /runs/preview
POST /runs
GET /runs
GET /runs/{run_id}
GET /runs/{run_id}/status
GET /runs/{run_id}/request
GET /runs/{run_id}/workflow
POST /runs/{run_id}/steps/{step_id}/submit
POST /runs/{run_id}/refresh
GET /runs/{run_id}/events
GET /runs/{run_id}/trace

这些 endpoint 对应当前 ApiService 的 framework-independent 方法。

Error model

当前 Rust ApiError 已经保留 HTTP-style status code：

400：invalid request 或 asset error
404：run、workflow 或 step not found
409：run id 冲突、step 已提交或已完成
500：I/O error

为什么 API 不直接执行 provider

LightFlow server 的 API 负责 workflow 控制，不负责 provider 实现。Provider、model、tool、thread、policy 和 audit 的执行面都应该走 CortexFS。

这样可以保持两层系统边界清晰：

LightFlow API 是 workflow control plane。
CortexFS 是 Linux execution and audit plane。

未来 HTTP adapter

未来加入 HTTP server 时，建议保持这个方向：

HTTP handler 只做 request/response adaptation。
业务逻辑继续在 ApiService。
不在 web framework 层重复 asset discovery 或 run file access。
OpenAPI contract 作为外部 client 的稳定入口。