Development

Development 文档汇总 Getting Started 之外的维护资料，包括概念词表、runtime 配置、reference、架构取舍和公开 API。

维护入口

入口	什么时候读
Concepts	对齐 task module、workspace model、task contract 和 glossary。
Runtime	维护 perago start、worker process、Conductor poll/result、LakeFS workspace publication。
Reference	核对 input/output contract、TaskDef 字段、环境变量、失败分类和 troubleshooting。
Architecture	理解 transaction model、publication fence 和 ADR 背后的取舍。
API Reference	查看公开 Python API、类型签名和 docstring。

Getting Started 深入

• Getting Started：任务声明总入口，包含最小 workspace task、核心命令、生成的 TaskDef 和 controls。

• Workspace Task：workspace task 的签名、字段边界和约束。

• Workspace-Free Task：workspace-free task 的 contract 和限制。

• Pydantic Contracts：Pydantic params/result contract 的精确规则。

• Guardrails：pre/post guardrail 的写法和约束。

• Controls and TaskDef：controls 到 TaskDef 字段的映射。

• Examples：可运行示例和反例索引。

Runtime 深入

• Runtime：runtime 总入口。

• Runtime Configuration：.env、进程环境变量和本机目录配置。

• CLI：perago check、extract、start 的 CLI 行为。

• Conductor Runtime：Conductor poll/result、attempt fence 和 worker 运行边界。

• LakeFS Runtime：LakeFS workspace 下载、同步和 cleanup。

• Workspace Publication：workspace publication 生命周期。

• Publish Budget：publish budget 与 responseTimeoutSeconds 的关系。

• Runtime Logging：worker 日志目录和日志字段。

• Worker Processes：supervisor、broker、executor 和 execution mode。

Reference 深入

• Reference：reference 总入口。

• Input/Output Contract：Conductor input/output contract。

• Conductor TaskDef：TaskDef 字段参考。

• Environment Variables：环境变量参考。

• Failure Classification：失败分类和结果状态。

• Troubleshooting：故障排查入口。

Architecture 深入

• Architecture：架构总入口。

• Workspace Transaction Model：事务模型和 fail-closed 边界。

• Publish Fences：publish fence 的保证和限制。

API 深入

• API Reference：公开 API 总入口。

• task、models、runtime、workspace、staging、config、results、errors 分类页都从这里进入。