AgentSkillsCN

temporal

帮助开发者运用 Temporal 实现持久化执行工作流。涵盖 CLI 命令、SDK 模式（Go、TypeScript、Python、Java）、工作流编排，以及架构决策。

SKILL.md
--- frontmatter
name: temporal
description: >-
  Help developers use Temporal for durable execution workflows. Covers CLI commands,
  SDK patterns (Go, TypeScript, Python, Java), workflow orchestration, and architectural
  decisions.
allowed-tools: [Read, Grep, Glob, Bash, WebSearch, WebFetch, Write, Edit]
user-invocable: true
metadata:
  author: rube-de
  version: "1.0.0"

Temporal Durable Execution

Comprehensive assistance for the Temporal durable execution platform: CLI operations, SDK development across Go/TypeScript/Python/Java, workflow design, and architectural decisions.

Triggers

Use this skill when the user mentions: "temporal", "durable execution", "workflow orchestration", "temporal cli", "temporal sdk", "temporal worker", "temporal activity", "temporal workflow", "temporal schedule", "temporal signal", "temporal query".

Quick Start

Local Development Server

bash
# Install CLI
brew install temporal    # macOS
curl -sSf https://temporal.download/cli | sh  # Linux

# Start local dev server (with Web UI at localhost:8233)
temporal server start-dev

# Start with persistent storage
temporal server start-dev --db-filename temporal.db

First Workflow (TypeScript example)

bash
npm init -y
npm install @temporalio/client @temporalio/worker @temporalio/workflow @temporalio/activity

Common Tasks by Intent

Developer wants to...Action
Start a workflowtemporal workflow start --type MyWorkflow --task-queue my-queue --input '{"key":"val"}'
Check workflow statustemporal workflow describe -w <workflow-id>
View event historytemporal workflow show -w <workflow-id>
Cancel a workflowtemporal workflow cancel -w <workflow-id>
Send a signaltemporal workflow signal -w <workflow-id> --name signal-name --input '{"data":true}'
Query workflow statetemporal workflow query -w <workflow-id> --name query-name
List running workflowstemporal workflow list
Debug stuck workflowCheck history with temporal workflow show, look for pending activities
Set up scheduled runstemporal schedule create --schedule-id my-sched --cron '0 * * * *' ...
Test workflowsUse SDK test utilities with time-skipping and activity mocking

When to Use Temporal

Good fit:

  • •Multi-step processes that must complete reliably (order processing, onboarding)
  • •Saga patterns across microservices (distributed transactions)
  • •Long-running workflows (days, weeks, months)
  • •Scheduled/cron jobs with complex logic
  • •Human-in-the-loop approval workflows

Not a good fit:

  • •Simple request/response APIs (use plain HTTP)
  • •Sub-millisecond latency requirements (Temporal adds overhead)
  • •Trivial fire-and-forget background jobs (use a simple queue)
  • •Pure data streaming (use Kafka/Flink)

Reference Documents

For deep dives, consult these references:

ReferenceContent
CLI.mdComplete CLI command reference: installation, server, workflows, schedules, operators
SDK-PATTERNS.mdCross-language SDK patterns: Go, TypeScript, Python, Java side-by-side
CONCEPTS.mdArchitecture, core concepts, design patterns, deployment, comparisons

Troubleshooting

Determinism Violations

Workflows must be deterministic. Common violations:

  • •Using Date.now(), Math.random(), or system time directly — use workflow.now() or side effects
  • •Making network calls from workflow code — move to activities
  • •Using non-deterministic data structures (e.g., iterating over unordered maps)
  • •Changing workflow logic without proper versioning

Stuck Workflows

  1. •Check event history: temporal workflow show -w <id>
  2. •Look for ActivityTaskScheduled without corresponding ActivityTaskCompleted
  3. •Verify workers are running and polling the correct task queue
  4. •Check activity timeouts — may need HeartbeatTimeout for long activities
  5. •Check for deadlocked signals/queries

Timeout Issues

Temporal has four timeout types:

  • •WorkflowExecutionTimeout: Max time for entire workflow (including retries)
  • •WorkflowRunTimeout: Max time for a single workflow run
  • •ScheduleToCloseTimeout: Max time from activity scheduled to completed
  • •StartToCloseTimeout: Max time from activity started to completed

If activities time out unexpectedly, ensure StartToCloseTimeout is generous enough and add heartbeating for long-running activities.

Worker Not Picking Up Tasks

  • •Verify task queue name matches between workflow starter and worker
  • •Check that the worker is registered with the correct workflow/activity types
  • •Ensure the Temporal server address is correct (TEMPORAL_ADDRESS)
  • •Look at worker logs for connection errors

Workflow

When helping with Temporal:

  1. •Identify the task: CLI operation, SDK code, architecture decision, or debugging
  2. •Check the language: For SDK questions, determine Go/TypeScript/Python/Java
  3. •Consult references: Use the reference docs for detailed patterns and commands
  4. •Verify determinism: For workflow code, ensure deterministic execution rules are followed
  5. •Test guidance: Recommend SDK test utilities, replay testing, and local dev server