Dispatcher SDK 使用指南

English | 简体中文

本指南面向 SDK 使用者，包括开发 Agent 应用的 Python 开发者。它介绍如何在 Python 应用中运行任务，并使用持久化状态、执行时限和显式恢复。应用负责业务 决策；Dispatcher 负责执行任务并投递结果。

从这里开始

1. 快速开始：安装当前代码并运行完整示例。
2. 托管任务：用 0.7 的 Dispatcher 接口提交任务，不必自己组装 Runtime、Orchestrator 和 Host。
3. 核心概念：理解 Runtime、Run、任务和宿主各自负责什么。
4. 接入指南：选择函数、脚本或工作流接入路径。
5. 沙箱执行：运行远程 Linux 脚本，了解清理和恢复边界。
6. 存储与本地恢复：查看 SQLite 积压、测量并发，并激活本地恢复副本。
7. 常见问题：排查待执行任务、重复通知和恢复状态。
8. 接入工程原则：准备可恢复的部署和可审查的证据。
9. 诊断与事件投影：检查部署身份和持久化事件，排查工作是否可用以及取消状态。
10. 执行观测与监督：读取已保存的活动、时限和子任务信息，并了解可选的停滞通知。

使用编程 Agent 接入 SDK 时，可让它先阅读英文 DocsforAgents。 详细 API 契约统一维护在 docs/SDK.md 和 公共 API 文档。部分详细指南目前只有中文；Wiki 的两种 语言版本都链接到同一份权威文档。关于如何核对版本和证据、在最终验证前固定 待发布版本，以及修改持久化对象前确认身份，见接入工程原则。

版本与范围

这些页面对应 0.7.2 代码，运行环境要求 Python 3.10 或更高版本。 文档要和代码版本匹配；旧版本可能没有这里介绍的接口。 如果要打开现有数据库，请先阅读存储与升级。

核心组件只依赖 Python 标准库和 SQLite。OpenSandbox 是可选扩展，需要额外依赖和服务。 进程隔离只用于控制可信代码的执行，不能当作文件系统或网络权限沙箱。