资产模型

LightFlow 的 asset 是项目可版本化的 Rust 文件。核心约束是：metadata 和 definition 放在同一个文件里。

为什么不用 sidecar JSON

Sidecar metadata 会让 agent 和 reviewer 在多个文件之间追踪真实状态。LightFlow 选择把 META 和定义放在一起，让一个文件就是一个完整资产。

这样有几个直接收益：

复制一个 asset 时不会遗漏 metadata。
删除一个 asset 时不会留下悬空 sidecar。
Review 时可以在同一处看到名称、类型、稳定性和行为。
Agent 修改 workflow 时不需要维护额外 registry。

目录约定

项目资产：


lightflow/models/*.rs
lightflow/nodes/*.rs
lightflow/compositions/*.rs
lightflow/workflows/*.rs

LightFlow 自带 built-ins：


src/builtins/nodes/*.rs
src/builtins/compositions/*.rs
src/builtins/workflows/*.rs

Metadata shape

当前 discovery 实现支持这个形状：


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,
};

kind 必须和所在目录匹配。比如 lightflow/nodes/*.rs 里的 asset 必须声明 AssetKind::Node。

Workflow definition shape

当前 workflow parser 支持一个明确受限的 builder chain：


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")
}

这个限制是有意的。它让 LightFlow 可以不执行任意 Rust 代码就提取 workflow definition。

支持的 step target

API step：


.api_step("draft", "node.llm_prompt", "openai.chat")

Tool step：


.tool_step("read_context", "node.read_context", "filesystem.read")

Thread step：


.thread_step("append_turn", "node.thread_message", "design-review")

Request template

当前内置 request template 是 openai_chat_input。它从 run inputs 的某个 string field 渲染 OpenAI chat request：


.openai_chat_input("llm.planner", "prompt")

如果 submit step 时不传显式 body，LightFlow 会用 run request 中的 inputs.prompt 生成 request。

演进方向

资产模型后续可以扩展，但应保持这些不变量：

discovery 不依赖 committed registry。
asset 文件可被 agent 单独理解。
workflow public contract 和执行结构保持可检查。
project asset 不和 engine source 混放。