MoonFlowGraph

我在维护科研自动化插件时，经常遇到一个不太显眼、但很影响复现的问题：任务清单写在计划里，依赖关系藏在代码里，运行结果又散落在日志和临时文件中。流程短的时候还能靠记忆串起来；一旦同时包含文献检索、数据准备、baseline、指标比较和报告撰写，就很难回答三个简单的问题：下一步能做什么，哪些步骤可以并行，这次运行到底留下了哪些证据。

MoonFlowGraph 是我对这个问题的一次小范围拆解。它用 MoonBit 提供任务图、DAG 校验、执行批次和 provenance trace，只负责把流程和证据说清楚，不替调用者执行模型或命令。

它适合解决什么

• 把科研实验拆成可检查的步骤，并在运行前发现缺失依赖或循环依赖。
• 为 Agent 或自动化脚本生成稳定的拓扑顺序和可并行批次。
• 记录每一步的输入、输出、状态与事件，形成便于复查和交接的 Markdown/JSON 记录。

核心能力

• 定义任务节点：id、标题、描述、输入、输出、标签和状态。
• 定义依赖边：表达 before -> after 的执行约束。
• 重复依赖检查：避免同一条边被重复记录和导出。
• DAG 校验：检查缺失任务、缺失依赖端点、循环依赖。
• 执行规划：生成拓扑顺序和可并行批次。
• 状态管理：提供受约束的正常执行迁移和不受约束的历史回放接口。
• 安全查询：返回与内部数组分离的任务、依赖、计划和 trace 快照。
• 公共封装：主要结构体字段不再直接暴露，外部代码通过 value()、outputs()、before()、batches()、message() 等访问器读取。
• 工作流导入：支持 workflow-spec-v1 JSON 导入、导出和 round trip；它和运行后的 JSON 快照是两套契约。
• 工作流命令入口：提供 cmd/workflow 和示例 JSON，用于导入、校验、规划、Mermaid 渲染和规范化 JSON 导出。
• 运行快照导入：支持严格读取 run-snapshot-v1 JSON，并校验图、序列化计划、trace 引用、生命周期顺序和最终任务状态。
• 快照审计入口：提供 cmd/audit、完整科研运行 fixture 和文件型 Bash wrapper。
• 就绪查询：同时支持调用方传入完成集合的 ready_tasks 和读取节点状态的 runnable_tasks。
• Provenance trace：按追加顺序记录事件，支持按任务过滤并查询最新事件。
• 一致性校验：在安全导出前拒绝过期计划和引用未知任务的 trace。
• 导出结果：生成 Markdown 报告、带版本号的 JSON 快照和 Mermaid 任务图。

它刻意不做什么

MoonFlowGraph 不是完整 Agent runtime。当前版本刻意不做这些事情：

• 不调用 LLM API。
• 不执行 shell 命令。
• 不管理分布式调度。
• 不保存密钥或凭证。
• 不提供 UI 或数据库持久化。

这些能力更适合由上层 runtime 负责。MoonFlowGraph 保持在“描述计划、检查依赖、记录证据”这一层，因而可以单独测试，也容易嵌入现有工具。

安装

在 MoonBit 项目中添加已经发布的包：

moon add AlexenderSokolov/moonflowgraph

在调用方包的 moon.pkg 中导入：

import {
  "AlexenderSokolov/moonflowgraph",
}

之后可通过默认别名 @moonflowgraph 使用公共 API。

仓库快速运行

需要本机已安装 MoonBit 工具链，并确保 moon 在 PATH 中。

moon fmt --check
moon info
git diff --exit-code -- '*.mbti'
moon check --deny-warn
moon build --deny-warn
moon test --deny-warn
moon run cmd/demo
moon run cmd/workflow
bash run_workflow.sh examples/research-workflow-v1.json
bash run_audit.sh examples/research-run-snapshot-v1.json

也可以运行仓库内脚本：

bash run_check.sh
bash run_demo.sh
bash run_workflow.sh examples/research-workflow-v1.json
bash run_audit.sh examples/research-run-snapshot-v1.json

一个具体例子

仓库里的 demo 模拟一次从文献和数据准备走向实验报告的流程：

collect_papers   prepare_dataset
      |                 |
      v                 v
extract_claims    run_baseline
      \                 /
       v               v
          compare_metrics -> write_report

第一批 collect_papers 和 prepare_dataset 可以并行；第二批 extract_claims 和 run_baseline 可以并行；之后汇合到 compare_metrics，最后进入 write_report。

trace 不只写“任务完成”，还会记录检索范围、数据快照、baseline 配置和比较依据。demo 最终输出：

• Markdown 报告：包含执行顺序、并行批次、任务元数据、状态和 trace。
• JSON 快照：包含任务、依赖、批次、输入输出、标签和 trace 事件，便于后续工具消费。
• Mermaid 任务图：可以直接嵌入 Markdown 文档或项目说明。

如果只想验证并规划一个 workflow-spec-v1 输入，不需要改 MoonBit 源码：

moon run cmd/workflow
bash run_workflow.sh examples/research-workflow-v1.json

第一个命令使用内置科研工作流示例；第二个命令由 Bash 读取示例 JSON 文件，再传给 cmd/workflow --json。

如果需要检查一次已记录的运行是否自洽，可以执行：

bash run_audit.sh examples/research-run-snapshot-v1.json

该命令只读取和审计快照，不执行任何任务；图、计划、trace 引用、生命周期或任务状态不一致时会以非零状态退出。

完整 API 和错误行为见 docs/API.md。 JSON 快照 v1 的正式契约见 docs/run-snapshot-v1.schema.json。 工作流输入 v1 的正式契约见 docs/workflow-spec-v1.schema.json。

API 示例

let graph = @moonflowgraph.FlowGraph::new()
guard graph.add_task(@moonflowgraph.TaskNode::new("collect_papers", "Collect papers")) is Ok(_) else { fail("add task") }
guard graph.add_task(@moonflowgraph.TaskNode::new("write_report", "Write report")) is Ok(_) else { fail("add task") }
guard graph.add_dependency(@moonflowgraph.TaskId::new("collect_papers"), @moonflowgraph.TaskId::new("write_report")) is Ok(_) else { fail("add dependency") }

guard graph.plan() is Ok(plan) else { fail("invalid graph") }
debug_inspect(plan.order().length(), content="2")
let trace = @moonflowgraph.Trace::new()
guard graph.to_json_checked(plan, trace) is Ok(snapshot) else { fail("invalid snapshot") }

let workflow_json = graph.to_workflow_spec().to_json()
guard @moonflowgraph.FlowGraph::from_workflow_json(workflow_json) is Ok(round_trip) else { fail("invalid workflow") }
debug_inspect(round_trip.task_count(), content="2")

guard @moonflowgraph.RunSnapshot::from_json(snapshot) is Ok(imported_snapshot) else { fail("invalid run snapshot") }
debug_inspect(imported_snapshot.audit() is Ok(_), content="true")

常用查询：

let _ = graph.transition_status(TaskId::new("collect_papers"), Running)
let _ = graph.predecessors(TaskId::new("write_report"))
let _ = graph.successors(TaskId::new("collect_papers"))
let _ = graph.ready_tasks([TaskId::new("collect_papers")])
let _ = graph.runnable_tasks()

当前状态

• 当前源码版本为 0.3.0。
• 本地硬门槛使用 MoonBit 0.10.3 验证：moon fmt --check、moon info、.mbti diff、moon check --deny-warn、moon build --deny-warn、moon test --deny-warn、demo 和两个 JSON CLI。
• moon test 当前共 48 项测试，覆盖大图、宽图、Workflow JSON、RunSnapshot 导入审计和 README 可执行示例。
• moon run cmd/bench 可输出机器可读的轻量 benchmark 摘要；CI 不强制跑基准，避免平台抖动。
• moon run cmd/demo 可以直接运行，并展示 Markdown、JSON 和 Mermaid 三种结果。
• moon run cmd/workflow 与 run_workflow.sh 可以展示 workflow import → validate → plan → export 的完整路径。
• run_audit.sh 可以审计 run-snapshot-v1 fixture 的图、计划、trace 生命周期和状态一致性。
• GitHub Actions 会执行格式、接口文件、检查、显式构建、测试、demo、workflow CLI 和 snapshot audit。

完整九项验收证据见 docs/ACCEPTANCE.md。

项目链接

• GitHub: https://github.com/AlexenderSokolov/moonflowgraph
• GitLink: https://gitlink.org.cn/SpringBack_25/moonflowgraph
• Mooncakes: https://mooncakes.io/docs/AlexenderSokolov/moonflowgraph

开发说明

项目为原创 MoonBit 实现，参考的是通用的 DAG、workflow 和 provenance 思路，不直接移植某个上游项目。开发过程中使用了 AI 辅助代码实现、测试和文档整理；选题、功能取舍、验收与提交由项目作者负责。

许可证

Apache-2.0。详见 LICENSE。