贡献与演进

LightFlow 还处在 backend foundation 阶段。贡献时最重要的是保持边界清楚。

修改 asset

项目资产放在 lightflow/ 下，不要混入 src/。

lightflow/models/
lightflow/nodes/
lightflow/compositions/
lightflow/workflows/

每个 asset 文件都应该保持自包含：

• META
• asset kind
• description
• stability
• workflow definition 或后续 node/composition definition

修改 engine

Engine source 放在 src/。如果你要加 HTTP server、runtime planner、scheduler 或 validator，优先考虑它属于哪个边界：

• API control plane：src/api.rs
• asset parsing：src/asset.rs
• XDG state：src/runs.rs
• CortexFS file ABI：src/cortex.rs
• CLI adapter：src/main.rs

不要复制 CortexFS 概念

Provider、model visibility、route、tool、MCP、thread、policy、audit 已经属于 CortexFS。LightFlow 应该记录引用和 correlation，不应该维护一套平行抽象。

推荐的下一批设计重点

1. 更明确的 workflow step 输入输出引用。
2. DAG 表达，而不仅是线性 step 列表。
3. Model alias 如何进入 CortexFS route context。
4. Node 和 composition 的 executable definition shape。
5. Schema validation 和 duplicate step id 检查。
6. HTTP adapter 对 ApiService 的薄封装。
7. 更完整的 integration test，覆盖 preview、create、submit、refresh。

测试建议

Rust 层优先跑：

cargo test

文档站优先跑：

cd docs-site
bun run build

如果你改了 OpenAPI contract，确保 Rust ApiService 和 CLI 输出仍然能映射到文档里的 endpoint 行为。