系统架构

LightFlow 的架构围绕一个分工：LightFlow 管 workflow authorship，CortexFS 管 Linux execution substrate。

模块地图

src/api.rs

Framework-independent backend service。CLI、未来 HTTP server、Unix socket server 都应该调用这个 service，而不是自己扫描 asset 或读写 run 文件。

src/asset.rs

解析自包含 Rust asset。当前实现使用 syn 读取顶层 pub const META，并支持一个受限的 workflow builder chain。

src/workflows.rs、src/nodes.rs、src/compositions.rs、src/models.rs

按 asset kind 扫描项目资产和 built-in 资产。它们是薄模块，真正共享逻辑在 src/asset.rs。

src/runs.rs

XDG-backed run store。负责 manifest、request、resolved workflow、events、trace 和 outputs 目录。

src/cortex.rs

CortexFS 路径规划和文件提交边界。它只做 path planning、tmp write、sync、rename、outbox read，不直接调用 provider。

src/main.rs

Linux-friendly CLI。它是 ApiService 的一个 adapter，不是业务逻辑核心。

数据流

Rust assets
  -> asset discovery
  -> workflow definition
  -> preview or create run
  -> XDG run manifest
  -> CortexFS inbox commit
  -> CortexFS outbox refresh
  -> updated manifest, events, trace

Asset discovery

LightFlow 扫描两类资产目录：

lightflow/<kind>/*.rs
src/builtins/<kind>/*.rs

Model 目前只有项目资产目录，没有 built-in model 目录。Node、composition、workflow 可以有 built-ins。

Run planning

创建 run 时，ApiService 会：

1. 生成或验证 run_id。
2. 找到 workflow asset。
3. 解析 workflow define()。
4. 验证 required model 和 step callable。
5. 为每个 step 规划 CortexFS exchange。
6. 写入 request、resolved workflow、events、manifest。

Preview 使用相同 planner，但不写 XDG state。

CortexFS boundary

CortexExchange::submit_request 的语义是：

1. 写入 *.tmp。
2. sync_all()。
3. 原子 rename 到 *.req.json。

只有最终 request suffix 出现时，CortexFS 才应该把它看作可执行请求。

API boundary

OpenAPI 是网络控制面，不替代 CortexFS。非 Linux client 可以通过 HTTP API 调用 LightFlow server，由 server 在 Linux host 上通过 /ctx 执行。

这个边界避免了两类问题：

• client 不需要解析 Rust source。
• LightFlow 不需要复制 CortexFS 已经拥有的 provider、tool、policy、audit 概念。