AgentSkillsCN

backend-async-tasks

在进行仓库变更时，务必坚持变更纪律、落实验证标准，并严格执行安全检查。

SKILL.md
--- frontmatter
name: backend-async-tasks
description: >
   Use when creating or updating Celery tasks, async job logic, or Beat schedules
   in the backend.
<!-- markdownlint-disable-file -->

Backend async tasks (Celery)

When to use

  • •You are adding or changing a Celery task in backend/src/backend/apps/**/tasks.py.
  • •You need to update the Celery Beat schedule in backend/src/backend/celery_app.py.
  • •You are adding DB access inside a Celery worker process.

Steps

  1. •Define tasks only in a tasks.py file under the relevant app module.
  2. •Decorate tasks with @app.task imported from backend.celery_app.
  3. •Return a typed result (int, None, etc.). Keep task-specific parameters local unless they must be environment-configured.
  4. •For DB access:
    • •Use asyncio.run() to bridge async work.
    • •Always acquire a session via get_task_session() from backend.celery_app.
  5. •For periodic jobs, update app.conf.beat_schedule in backend/src/backend/celery_app.py and use celery.schedules.crontab.

Constraints and guardrails

  • •Never use the global alchemy_config engine inside a task; it is not fork-safe for Celery workers.
  • •Always use get_task_session() to manage DB connections safely across worker processes.

References

  • •backend/src/backend/apps/**/tasks.py
  • •backend/src/backend/celery_app.py
  • •backend/tests/apps/users/test_tasks.py