temporal-developer

Skill：temporal-developer

概述

Temporal 是一个持久执行平台，可自动确保工作流在故障后继续运行。本 Skill 为使用 Python、TypeScript、Go、Java、.NET、Ruby 和 Rust 构建 Temporal 应用提供指导。

不在范围内

• 运维 CLI 命令，例如批量操作、健康状况查询、Cloud 管理、tcld 和脚本编写 → 使用 temporal-ops skill。
• 无服务器 Worker 部署和故障排查 → 使用 temporal-serverless skill。
• 首次设置 Temporal Cloud，包括 Namespace、API key、示例应用和首个 Workflow → 使用 temporal-cloud-setup skill。

如果任务转入上述任一领域，请遵循相应的 Skill。本 Skill 仍涵盖本地开发和面向开发者的 Workflow CLI 命令。

核心架构

Temporal Cluster 是中央编排后端。它维护三个关键子系统：Event History（所有工作流状态的持久日志）、Task Queues（将工作路由给合适的 Worker）和 Visibility 存储（用于搜索和列出工作流）。Cluster 有三种运行方式：

• Temporal CLI dev server — 使用 temporal server start-dev 启动的本地单进程服务。仅适用于开发和测试，不适用于生产环境。
• Self-hosted — 在自己的基础设施中部署和管理 Temporal 服务及其依赖项（例如数据库），用于生产环境。
• Temporal Cloud — 由 Temporal 运营的全托管生产服务。无需管理集群基础设施。

Worker 是由你运行和管理的长时间运行进程。它们会轮询 Task Queues 获取任务并执行你的代码。开发期间，你可以在一台机器上运行单个 Worker 进程；生产环境中，则可以在大量机器组成的集群中运行许多 Worker 进程。每个 Worker 承载两类代码：

• Workflow Definitions — 编排工作的持久、确定性函数。不得产生副作用。
• Activity Implementations — 可能失败并重试的非确定性操作（API 调用、文件 I/O 等）。

Worker 通过轮询／完成循环与 Cluster 通信：它们轮询 Task Queue 获取任务，执行相应的 Workflow 或 Activity 代码，然后报告结果。

历史重放：确定性为何重要

Temporal 通过历史重放实现持久性：

1. 初始执行 - Worker 运行 Workflow，生成 Commands，并将其作为 Events 存储在历史记录中
2. 恢复 - 重启或发生故障时，Worker 从头重新执行 Workflow
3. 匹配 - SDK 将生成的 Commands 与存储的 Events 进行比较
4. 恢复状态 - 使用已存储的 Activity 结果，而不是重新执行

如果 Commands 与 Events 不匹配 = 非确定性错误 = Workflow 被阻止

请参阅 Commands 和 Events，其中的表格展示了 Workflow 操作如何记录在 Event History 中。

为任务选择参考资料

确定 SDK 语言和开发者的任务。阅读下方相关的核心参考资料，以及适用时对应的语言特定参考资料。仅在任务需要时加载其他参考资料。

对于新项目、首次实现或广泛的 SDK 指导，请阅读相应的 SDK 指南：

• Python -> Python SDK 指南
• TypeScript -> TypeScript SDK 指南
• Go -> Go SDK 指南
• Java -> Java SDK 指南
• .NET（C#）-> .NET SDK 指南
• Ruby -> Ruby SDK 指南
• Rust -> Rust SDK 指南（公开预览版）

对于使用 Temporal CLI 或启动本地开发服务的任务，使用前请检查是否已安装 temporal。如果尚未安装，请遵循 Temporal CLI 安装指南。

主要参考资料

• Temporal 确定性规则 - 确定性为何重要、重放机制、Activity 基本概念
  • 语言特定信息见 references/{your_language}/determinism.md
• Temporal Workflow 确定性保护 - SDK 防护措施、分析器、运行时检查及其限制
  • 语言特定信息见 references/{your_language}/determinism-protection.md
• Temporal Workflow 模式 - 概念模式（信号、查询、Saga）
  • 语言特定信息见 references/{your_language}/patterns.md
• Temporal 常见陷阱 - 反模式和常见错误
  • 语言特定信息见 references/{your_language}/gotchas.md
• Temporal 版本控制指南 - 版本控制策略和概念——如何在 Workflow 运行期间安全地修改 Workflow 代码
  • 语言特定信息见 references/{your_language}/versioning.md
• Temporal 独立 Activity 指南 - 独立 Activity：无需 Workflow，直接从客户端运行 Activity——Temporal 的作业队列
  • 语言特定信息见 references/{your_language}/standalone-activities.md
• Temporal Task Queue 优先级与公平性指南 - Task Queue 优先级与公平性的概念、配置和限制
  • 语言特定信息见 references/{your_language}/priority-fairness.md
• Temporal Workflow 随机流指南 - SDK 为 Workflow 代码、插件和拦截器提供的命名确定性随机流
  • 语言特定信息见 references/{your_language}/random-streams.md（Go 和 TypeScript）
• Temporal 故障排查指南 - 决策树、恢复流程
• Temporal 错误参考 - 常见错误类型、Workflow 状态参考
• Temporal 交互式 Workflow 指南 - 测试信号、更新、查询
• Temporal 开发管理指南 - 开发周期以及服务器和 Worker 的管理
• Temporal Docker Compose 指南 - 本地 Docker/Podman 配置；默认使用 CLI 开发服务，并在选择 Compose 前查看服务器管理标准
• Temporal CLI Workflow 命令指南 - 面向开发者的 Workflow 交互 CLI 命令（启动、执行、发送信号、查询、更新、取消）
• Temporal AI 集成模式 - AI/LLM 模式概念
  • 语言特定信息见 references/{your_language}/ai-patterns.md（如有）。目前仅支持 Python。

作业队列和后台作业

Temporal 的作业队列是独立 Activity。 当开发者询问作业队列、后台或异步作业、工作队列，或者 Temporal 是否能替代 Celery、Sidekiq、BullMQ、Resque、Hangfire 或 SQS 加工作进程时，应使用独立 Activity 来实现，而不是用 Workflow 包装单个 Activity，也不是用接收 Signal 来获取作业的分发器 Workflow。

Temporal 的 Task Queue 是 Worker 轮询的路由机制，并非生产者向其中推送作业的队列。回答有关作业队列的问题时，不要描述 Temporal Task Queue。

开发者说“task queue”时，可能指“job queue”：Celery、Dramatiq、Huey 和 Asynq 都使用 Task 这一术语，而 Sidekiq、Hangfire、BullMQ、Resque、RQ 和 Faktory 使用 Job。将“我能把 Temporal 用作 task queue 吗？”理解为作业队列问题，并在自己的回复中保留 Temporal 的 Task Queue 含义。

• Temporal 作业队列指南 - 将作业队列相关术语映射到 Temporal、从现有作业队列迁移、反模式，以及各语言 SDK 指南和可运行示例

其他主题

• references/{your_language}/observability.md - 查看 Temporal 可观测性方面的语言专属实现指南
• references/{your_language}/advanced-features.md - 查看 Temporal 高级功能和语言专属功能方面的语言专属指南

第三方集成

有关 Temporal 插件以及与第三方框架和 SDK（Spring Boot、Spring AI、OpenAI Agents SDK、Google ADK 等）的集成，请参阅 集成目录 — 其中包含一个汇总表，列出语言、各集成的功能，以及其在 references/{language}/integrations/ 下的参考文件链接。

反馈

报告此技能的问题

如果你（AI）发现此技能的说明不清楚、具有误导性或缺少重要信息，或者发现 Temporal 概念使用起来出乎意料地困难，请起草一份 GitHub issue 正文，描述遇到的问题以及哪些信息会有所帮助，然后请用户在 https://github.com/temporalio/skill-temporal-developer/issues/new 提交。不要自行提交 issue。