Task Contract#

Task contract 只来自 Python 函数签名和 Pydantic models。Perago 不要求也不允许在 @task(...) 中重复声明 params 或 output schema。

Workspace task contract#

workspace task worker 的合法函数签名如下：

from pathlib import Path

from pydantic import BaseModel

class Params(BaseModel):
    source: str

class Output(BaseModel):
    rows: int

def build_features(workspace: Path, params: Params) -> Output:
    ...

它对应的外部 contract 是：

input required: workspace
input required: params
output generated: workspace
output generated: result

workspace 参数由 Perago 注入为本地 attempt workspace path。params 由 Conductor input 中的 params 字段解析。返回值被序列化到 output 的 result 字段。

Workspace-free task contract#

workspace-free task worker 的合法函数签名如下：

from pydantic import BaseModel

class Params(BaseModel):
    value: int

class Output(BaseModel):
    doubled: int

def double(params: Params) -> Output:
    ...

它对应的外部 contract 是：

input required: params
output generated: result

workspace-free task 不声明 WorkspaceSpec(...)，也不接收 workspace: Path。

Required, optional, generated#

Perago 文档中使用这三个标签描述 contract 字段来源：

required：调用方必须在 Conductor input 中提供，例如 workspace 和 params。
optional：task metadata 或 controls 中可以不声明、由默认值补齐的字段，例如 WorkspaceSpec(prefix="/")。
generated：Perago 在运行时或 TaskDef 生成时产生的字段，例如 output workspace.ref 和 TaskDef JSON 中的 derived timeout。

业务字段是否 required 由 Pydantic params model 决定。Perago 不把业务字段展开到 Conductor input 顶层。

拒绝场景#

以下函数签名会被 Perago MVP contract 拒绝：

同一个 module 里定义多个 task workers。
workspace task 缺少 workspace=WorkspaceSpec(...)。
workspace-free task 声明 workspace=WorkspaceSpec(...)。
参数名缺少 workspace 或 params。
展开业务字段，例如 def task(workspace: Path, source: str) -> Output。
async def task worker。
默认参数、keyword-only 参数、*args 或 **kwargs。
缺少 params 类型注解或返回类型注解。
在 @task(...) 中重复声明 params 或 output schema。

这些错误会在 import-time validation、perago check 或 worker 启动阶段失败，业务函数执行前即可暴露。