LinkedRun

LinkedRun 是一个以 MCP 服务器形式暴露的持久化本地 Task–Artifact DAG 执行器。

任务消费不可变工件，并产出不可变工件。一个新任务可以依赖同一批次提交的任务输出，也可以依赖任何更早提交的任务输出。因此此图会增量增长，而不是被单个工作流运行所限定。

LinkedRun 刻意是一个纯机制内核。它不知道训练、评估、细胞聚类、ARI、模型或实验协议是什么。它也不预测资源需求：提交 Agent 声明资源，LinkedRun 信任该声明，只受机器容量限制和运行时预留约束。

为什么

预期的分工是：

• task Agent：决定what要运行，并声明资源需求；

• project tooling：预测资源、验证模型、构建工作流、计算指标；

• LinkedRun：持久化依赖，无忙等轮询，保留和取消、运行与取消进程，提交工件，并发行持久事件。

核心概念

Artifact -> Task -> Artifact
                \\-> Task -> Artifact

一个数据依赖也是一个执行依赖。当某个工件未被依赖时，可以通过 control 提供纯排序约束。

MCP 工具

• submit_task

• submit_graph

• get_task

• list_tasks

• cancel_task

• retry_task

• list_artifacts

• get_artifact

• get_graph

• get_events

• watch_events

• resource_status

watch_events 是一个持久化长轮询接口：客户端从最后的 event_id 恢复，因此无需紧密轮询。未来发布版可以在支持基础充份时，将执行句柄映射到 MCP 的 io.modelcontextprotocol/tasks 扩展。

安装

pip install -e .

需要 Python 3.11+。LinkedRun 以 MCP Python SDK v2 / MCP 2026-07-28 为目标。

启动

持久化本地 HTTP 服务（当多个 Agent / 客户端需要同一图时，推荐使用）：

export LINKEDRUN_HOME="$HOME/.linkedrun"
linkedrun --transport streamable-http --host 127.0.0.1 --port 8765

MCP 端点位于 http://127.0.0.1:8765/mcp。

对于自身管理 MCP 进程的主机：

linkedrun --transport stdio

SQLite 状态与内容寻址工件都储存在 LINKEDRUN_HOME 下。

提交单个任务

从概念上讲，对 submit_task 的一次 MCP 调用看起来像：

{
  "name": "train",
  "command": ["python", "train.py"],
  "outputs": {
    "model": "outputs/model.pt",
    "embedding": "outputs/embedding.zarr"
  },
  "resources": {
    "cpu_cores": 8,
    "memory_bytes": 34359738368,
    "gpu_count": 1,
    "gpu_mode": "exclusive"
  }
}

命令为 argv 数组，而不是 shell 的字符串。只有在需要 shell 语义时，才显式使用 ["bash", "-lc", "..."]。

同批次提交依赖

submit_graph 支持提交本地引用：

{
  "tasks": [
    {
      "name": "train",
      "command": ["python", "train.py"],
      "outputs": {"embedding": "outputs/embedding.zarr"}
    },
    {
      "name": "cluster",
      "command": ["python", "cluster.py"],
      "inputs": {"embedding": "@train/embedding"},
      "outputs": {"clusters": "outputs/clusters.parquet"}
    },
    {
      "name": "ari",
      "command": ["python", "ari.py"],
      "inputs": {"clusters": "@cluster/clusters"}
    }
  ]
}

整个批次在环检测后原子注册。

跨提交依赖

如果一个旧有的 task_ab 训练任务ID产生了 embedding，那么早期一个任务在之后提交时就可以引用它：

{
  "inputs": {
    "embedding": "task:task_abcd/artifact:embedding"
  }
}

一个已提交的工件可直接引用：

artifact:art_abcd

因此这种依赖是一个持久化、增量的：不需要一个“workspace班界”来设计。

不能依赖，遂自包容提交。需要一个 task directory task.configs。

运行时契约

任务开始前，LinkedRun 会创建私有任务/工作目录并设置：

LINKEDRUN_TASK_ID
LINKEDRUN_ATTEMPT_ID
LINKEDRUN_WORKDIR
LINKEDRUN_OUTPUT_DIR
LINKEDRUN_INPUT_<NAME>

每个输入都是一个读取于约定的符号链接，指向不可变内容寻址存储物。约定输出路径必须保持在任务目录内。进程成功退出后，输出依据哈希，提交至工件存储库，随后任务设为 SUCCEEDED。

任务状态

PENDING -> READY -> RUNNING -> SUCCEEDED
                       \\----> FAILED
PENDING --------------------> BLOCKED      (upstream failed/missing artifact)
PENDING --------------------> UNSCHEDULABLE (declared request exceeds machine capacity)
PENDING/RUNNING ------------> CANCELED

重试会使每次尝试的世代（generation）计数增加。一旦旧 generation 过期，旧的 attempt 不得再 commit；这是 LinkedRun 的围栏规则的第一步。

资源策略

LinkedRun 不承担资源能力。它接受：

cpu_cores
memory_bytes
gpu_count
gpu_mode=exclusive
gpu_memory_bytes_hint
walltime_seconds
scratch_bytes

gpu_memory_bytes_hint 在 v0.1 仅供证明/元数据。GPU 调度为独占式设备分配。CPU 与内存为保留预算，而 walltime_seconds 会被执行。OS 级别的 CPU/内存/scratch 硬隔离被故意留给之后的 sandbox 模块，而不是把实验特化的准入逻辑加入内核。

当前 v0.1 边界

Implemented：

• SQLite/WPA（WAL）持久化任务、尝试、依赖、工件和事件状态；

• 原子注册、批次图注册以及循环检测；

• 使用相同批次引用任务/工件并保证执行顺序；

• 后台依赖调度；

• 调用方声明的 CPU/内存/GPU 预留；

• 通过 CUDA_VISIBLE_DEVICES 获得独占 GPU 分配；

• 子进程执行、取消保护和 walltime 限制；

• 内容寻址的不可变文件/目录工件；

• 持久事件与可重连的长轮询；

• 重试 generation/围栏；

• stdio 和 Streamable HTTP MCP 传输。

尚未加固：

• 用于 CPU、内存、scratch 的 OS cgroup/job-object 硬限制；

• 在已重新重新接入正在运行的子进程时，经受机器崩溃（v0.1 目前会安全地将中断尝试标记为失败，并需要显式地 retry）；

• 非本机 HTTP 暴露时的认证；

• MCP Tasks 扩展映射；

• 垃圾回收/retention 策略在远程 worker 或分布式调度上执行（当前不必）。

这是有意的：v0.1 先建立最小内核边界，再在以后增加可选机制。

Development

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
pytest -q
ruff check .

架构规则

如果一项功能可以在不破坏通用任务持久化、依赖调度、进程生命周期、工件提交或事件持久性的前提下从 LinkedRun 中移出，那它就应该放在 LinkedRun 外部。尤其像模型/实验验证、资源预测、实验协议语义、指标语义和正式结果发布，都是外部关注点。