核心概念

Node

Node 是最小可复用 pipeline 单元。项目 node 放在：


lightflow/nodes/*.rs

Node 文件至少包含 META，用于描述 id、title、kind、description 和 stability。后续 node 可以继续承载输入输出 schema、执行约束、资源需求和 UI hints。

Composition

Composition 是由 node 或其他 composition 组成的可复用模式。它不应该成为隐藏 runtime magic，而应该把常见 pipeline 结构显式命名和复用。

项目 composition 放在：


lightflow/compositions/*.rs

Workflow

Workflow 是顶层 pipeline definition。它定义公开输入、公开输出、需要的 model alias，以及每个 step 如何映射到 CortexFS execution target。

项目 workflow 放在：


lightflow/workflows/*.rs

示例：


use lightflow::asset::*;
 
pub const META: AssetMeta = AssetMeta {
    id: "workflow.text_plan",
    title: "Text Plan",
    kind: AssetKind::Workflow,
    description: "Drafts a concise plan from a text prompt through CortexFS.",
    stability: Stability::Draft,
};
 
pub fn define() -> WorkflowDef {
    workflow(META.id)
        .input_schema("schemas/text_plan.input.json")
        .output_schema("schemas/text_plan.output.json")
        .required_model("llm.planner")
        .api_step("draft", "node.llm_prompt", "openai.chat")
        .openai_chat_input("llm.planner", "prompt")
}

Model

Model asset 不是大模型权重本身。它描述项目里的 model alias、能力、provider 期待和 artifact hints。

项目 model 放在：


lightflow/models/*.rs

Workflow 引用 model alias，而不是硬编码本地路径：


.required_model("llm.planner")

运行时可用模型和路由能力由 CortexFS 用户视图决定。

Run

Run 是一次 workflow 请求的运行记录。LightFlow 记录 workflow 结构、step 状态、CortexFS request path、response path、error path、fingerprint 和 route metadata。

真实 run state 不提交到仓库，而是放在 XDG state：


$XDG_STATE_HOME/lightflow/runs/<run_id>/

CortexFS

CortexFS 是 Linux execution substrate。LightFlow 通过 /ctx 与它交互，不重新实现 provider、tool、MCP、thread、policy、audit。

典型 API step 会映射到：


/ctx/home/<uid>/api/<format>/inbox/<step_id>.req.json
/ctx/home/<uid>/api/<format>/outbox/<step_id>.resp.json
/ctx/home/<uid>/api/<format>/outbox/<step_id>.error