Development

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

维护入口

入口	什么时候读
Concepts	对齐 task module、workspace model、task contract 和 glossary。
Runtime	维护 perago start、worker process、Conductor poll/result、LakeFS workspace publication。
Architecture	理解 transaction model、publication fence 和 ADR 背后的取舍。
API Reference	查看公开 Python API、类型签名和 docstring。

Getting Started 深入

• Getting Started：简短入口和阅读路线，不承载长篇规则细节。

• 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 字段的映射。

• Commands：check、extract、start 的本地使用路径。

• Failure Signaling：业务分支、retryable failure 和 terminal failure 的选择边界。

• 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。

Architecture 深入

• Architecture：架构总入口。

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

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

API 深入

• API Reference：公开 API 总入口。

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