celery-task

Celery 任务派发技能

Celery 异步任务管理和派发技能，支持跨平台部署和独立技能环境。

⚠️ 重要提醒

本技能使用独立的虚拟环境（.venv），所有命令必须使用技能虚拟环境中的 Python 执行，不能使用系统 Python。

系统	Python 路径
Windows	.venv\Scripts\python.exe
Linux/macOS	.venv/bin/python

目录

• 快速开始
• 核心概念
• 脚本工具
• 定时任务
• 使用场景
• 配置说明
• ntfy 通知推送
• 跨平台支持
• 常见问题

---

快速开始

首次使用

1. 安装 Redis

系统	安装方式	启动命令
Windows	Memurai	net start Memurai
Linux	sudo apt-get install redis-server	sudo systemctl start redis
macOS	brew install redis	brew services start redis

2. 设置技能环境

# 进入技能目录
cd C:\Users\YourName\.claude\skills\celery-task    # Windows(建议使用powershell语法)
cd ~/.claude/skills/celery-task                    # Linux/macOS

# 使用系统 Python 创建技能虚拟环境
python scripts/setup_env.py

日常使用

⚠️ 三个必要服务

技能需要以下三个服务同时运行才能正常工作：

• Redis/Memurai：消息队列和任务存储
• Celery Worker：任务执行进程
• Flower 监控：Web 监控界面

🤖 AI 助手职责：检查服务状态时，如果发现任何一个服务未运行，必须立即启动它。三个服务都是必要的，缺一不可。

1. 进入技能目录

# Windows
cd C:\Users\YourName\.claude\skills\celery-task

# Linux/macOS
cd ~/.claude/skills/celery-task

2. 检查服务状态

# Windows（技能目录下）
.venv\Scripts\python.exe scripts/check_services.py

# Linux/macOS（技能目录下）
.venv/bin/python scripts/check_services.py

3. 启动 Worker（后台运行）

🤖 AI 助手自动处理：当检测到 Worker 未运行时，AI 助手应自动在后台启动 Worker。

# Windows（技能目录下）- 后台运行
.venv\Scripts\python.exe scripts/worker.py

# Linux/macOS（技能目录下）- 后台运行
.venv/bin/python scripts/worker.py

提示：Worker 需要持续运行。使用后台运行模式，无需保持终端窗口开启。

4. 启动 Flower 监控（后台运行）

🤖 AI 助手自动处理：当检测到 Flower 监控未运行时，AI 助手应自动在后台启动 Flower。

# Windows（技能目录下）
.venv\Scripts\python.exe scripts/start_monitoring.py

# Linux/macOS（技能目录下）
.venv/bin/python scripts/start_monitoring.py

5. 派发任务预检查

用户要求派发任务执行的任何命令或者脚本或者你自己编写的 Python 脚本在派发任务前必须先运行一遍以保证不会出错，如果当前不适合直接运行，编写可从其他角度验证任务命令是否正确的脚本进行验证。(额外的验证脚本验证完成后需要删除)

6. 派发任务

🤖 AI 助手自动处理：

• 派发任务前检查服务状态
• 发现任何一个服务未运行时，自动启动该服务
• 三个必要服务：Redis/Memurai、Celery Worker、Flower 监控
• 不应要求用户手动启动服务
• 只有在无法自动启动（如权限问题）时才提示用户

# Windows（技能目录下） - 立即执行
.venv\Scripts\python.exe scripts/dispatch.py "echo 'Hello'"

# Windows（技能目录下） - 延迟执行（推荐使用 --bg）
.venv\Scripts\python.exe scripts/dispatch.py "echo 'Hello'" --delay 60 --bg

# Linux/macOS（技能目录下）
.venv/bin/python scripts/dispatch.py "echo 'Hello'"
.venv/bin/python scripts/dispatch.py "echo 'Hello'" --delay 60 --bg

注意：派发完成任务后，需要立即检查任务状态，确认任务是否已被接受，另外再次告诉用户可以访问 http://localhost:5555 查看任务状态。

在项目环境执行命令

当需要执行项目中的命令时，使用完整路径指定项目的可执行文件。示例：

# 派发前先测试命令
"C:\project\.venv\Scripts\aishare.exe" 002957

# 确认可执行后派发（使用技能虚拟环境）
.venv\Scripts\python.exe scripts/dispatch.py "C:\project\.venv\Scripts\aishare.exe 002957" --delay 60 --bg

详见 跨平台部署指南

---

核心概念

三个必要服务

服务	作用	必要性
Redis/Memurai	消息队列和任务存储	✅ 必要
Celery Worker	执行任务的进程，需要持续运行	✅ 必要
Flower 监控	Web 监控界面，实时查看任务状态	✅ 必要

重要：三个服务都是必要的，任何一个未运行都会影响技能的正常使用。AI 助手必须确保所有服务都在运行。

其他概念

术语	说明
countdown	延迟执行参数（秒），推荐使用
eta	指定具体执行时间（一次性定时任务）
solo pool	单进程并发模式（Windows 默认）
prefork pool	多进程并发模式（Linux/macOS 默认）

---

脚本工具

前提条件：执行以下命令前，必须先进入技能目录。

Windows：

cd C:\Users\YourName\.claude\skills\celery-task

Linux/macOS：

cd ~/.claude/skills/celery-task

然后使用技能虚拟环境的 Python 执行脚本。

setup_env.py - 环境设置

# 使用系统 Python 创建技能虚拟环境
python scripts/setup_env.py

自动创建虚拟环境并安装依赖（celery、redis、flower）。

worker.py - 启动 Worker

# Windows（技能目录下）
.venv\Scripts\python.exe scripts/worker.py

# Linux/macOS（技能目录下）
.venv/bin/python scripts/worker.py

# 调试模式（技能目录下）
.venv\Scripts\python.exe scripts/worker.py -l debug

# 禁用事件追踪（技能目录下）
.venv\Scripts\python.exe scripts/worker.py --no-events

注意：Worker 需要在新终端窗口中保持运行。

dispatch.py - 任务派发

# Windows（技能目录下）
.venv\Scripts\python.exe scripts/dispatch.py "command"
.venv\Scripts\python.exe scripts/dispatch.py "command" --delay 60 --bg
.venv\Scripts\python.exe scripts/dispatch.py --task-id <task-id>

# Linux/macOS（技能目录下）
.venv/bin/python scripts/dispatch.py "command"
.venv/bin/python scripts/dispatch.py "command" --delay 60 --bg
.venv/bin/python scripts/dispatch.py --task-id <task-id>

参数说明：

参数	说明
command	要执行的命令（必填）
--delay, -d	延迟执行（秒）
--eta	指定执行时间（YYYY-MM-DD HH:MM:SS）
--bg, --background	后台派发，不等待结果
--timeout, -t	命令超时时间（秒，默认 300）
--cwd	指定工作目录
--task-id	查询指定任务状态

check_services.py - 服务检查

# Windows（技能目录下）
.venv\Scripts\python.exe scripts/check_services.py

# Linux/macOS（技能目录下）
.venv/bin/python scripts/check_services.py

检查内容：

• Redis/Memurai 进程和连接状态
• Celery Worker 进程和响应状态
• Flower 监控服务状态

重要：三个服务都是必要的。如果检查结果显示任何服务未运行，AI 助手必须立即启动该服务。

start_monitoring.py - 启动监控

重要：Flower 监控是三个必要服务之一。如果未运行，AI 助手必须启动它。

# Windows（技能目录下）
.venv\Scripts\python.exe scripts/start_monitoring.py

# Linux/macOS（技能目录下）
.venv/bin/python scripts/start_monitoring.py

# 自定义端口（技能目录下）
.venv\Scripts\python.exe scripts/start_monitoring.py --port 8888

访问地址：http://localhost:5555

---

使用场景

スケジュールタスク（eta パラメーターを使用）

--eta パラメーターを使用して、タスクの実行時刻を指定します（一度だけ実行します）。

# Windows - 明天早上8点执行
.venv\Scripts\python.exe scripts/dispatch.py "backup.py" --eta "2026-02-16 08:00:00" --bg

# Linux/macOS - 下周一早上9点执行
.venv/bin/python scripts/dispatch.py "weekly_report.py" --eta "2026-02-17 09:00:00" --bg

# 2小时后执行
.venv\Scripts\python.exe scripts/dispatch.py "python system_update.py" --delay 7200 --bg

eta パラメーターの説明：

• 実行時刻を指定します（形式：YYYY-MM-DD HH:MM:SS）
• タスクは一度だけ実行され、完了後に終了します
• 一時的な遅延タスク（「明日の午後3時に実行」「来週実行」など）に適しています
• --bg パラメーターと併用すると、タスクの登録後すぐに戻ります

---

---

前提条件：以下のコマンドを実行する前に、必ずスキルディレクトリに移動し、スキルの仮想環境の Python を使用してください。

Windows：

cd C:\Users\YourName\.claude\skills\celery-task

Linux/macOS：

cd ~/.claude/skills/celery-task

シナリオ 1：プロジェクト環境でコマンドを実行する

コマンドラインツールと Python モジュールを区別します：

# 命令行工具 - 直接使用完整路径
# Windows（在技能目录执行）
.venv\Scripts\python.exe scripts/dispatch.py "C:\project\.venv\Scripts\aishare.exe 002957" --delay 60 --bg

# Linux/macOS（在技能目录执行）
.venv/bin/python scripts/dispatch.py "/home/user/project/.venv/bin/aishare 002957" --delay 60 --bg

# Python 模块 - 使用 python.exe -m
# Windows（在技能目录执行）
.venv\Scripts\python.exe scripts/dispatch.py "C:\project\.venv\Scripts\python.exe -m module_name args" --delay 60 --bg

# Linux/macOS（在技能目录执行）
.venv/bin/python scripts/dispatch.py "/home/user/project/.venv/bin/python -m module_name args" --delay 60 --bg

シナリオ 2：特定のディレクトリにあるスクリプトを実行する

# 使用 --cwd 指定工作目录
# Windows（在技能目录执行）
.venv\Scripts\python.exe scripts/dispatch.py "python data_process.py" --cwd "C:\project" --delay 120

# Linux/macOS（在技能目录执行）
.venv/bin/python scripts/dispatch.py "python data_process.py" --cwd "/home/user/project" --delay 120

シナリオ 3：複数のタスクを一括で登録する

# Windows（在技能目录执行）
.venv\Scripts\python.exe scripts/dispatch.py "python task1.py" --delay 60
.venv\Scripts\python.exe scripts/dispatch.py "python task2.py" --delay 120
.venv\Scripts\python.exe scripts/dispatch.py "python task3.py" --delay 180

# Linux/macOS（在技能目录执行）
.venv/bin/python scripts/dispatch.py "python task1.py" --delay 60
.venv/bin/python scripts/dispatch.py "python task2.py" --delay 120
.venv/bin/python scripts/dispatch.py "python task3.py" --delay 180

シナリオ 4：eta を使用して一度だけ実行するスケジュールタスクを設定する

特定の時刻に一度だけタスクを実行する場合は、--eta パラメーターを使用します：

# 明天早上 8 点执行数据导出
.venv\Scripts\python.exe scripts/dispatch.py \
  "python export_data.py" \
  --eta "2026-02-17 08:00:00" \
  --bg

# 下周五下午 6 点发送周报
.venv\Scripts\python.exe scripts/dispatch.py \
  "python send_report.py weekly" \
  --eta "2026-02-21 18:00:00" \
  --bg

# 2 小时后执行系统更新
.venv\Scripts\python.exe scripts/dispatch.py \
  "python system_update.py" \
  --delay 7200 \
  --bg

---

設定

基本設定

設定ファイルは celery_tasks/worker.py にあります：

# Broker
broker_url = 'redis://localhost:6379/0'

# 时区
timezone = 'Asia/Shanghai'
enable_utc = True

# 任务确认
task_acks_late = True
task_reject_on_worker_lost = True

カスタム設定

# 复制配置模板
cp assets/config/celery_config.py your_project/

# 修改并使用
from celery import Celery
app = Celery('myapp')
app.config_from_object('celery_config')

詳しくは設定リファレンスを参照してください。

---

ntfy 通知のプッシュ配信

このスキルには ntfy のプッシュ通知機能が統合されており、タスクの完了時に通知をスマートフォンへ自動送信します。

主な機能

• タスク完了通知：タスクの実行に成功／失敗したときに自動で通知をプッシュします
• バックグラウンドでのプッシュ：画面ロック中やバックグラウンド状態でも通知を受信できます
• 複数端末での同期：スマートフォンとパソコンで同時に購読できます
• 優先度の設定：タスクの状態に応じて通知の優先度を自動設定します

設定方法

1. ntfy サーバーをインストールする（任意）

システム	インストール方法
Windows	ntfy.exe をダウンロードするか、scoop install ntfy を実行
Linux	wget https://github.com/binwiederhier/ntfy/releases/download/v2.17.0/ntfy_2.17.0_linux_amd64.tar.gz
macOS	brew install ntfy

または公式サーバー https://ntfy.sh を使用します（FCM が設定済みのため、インストールは不要です）。

2. ntfy サーバーを起動する

# Windows
ntfy serve

# Linux/macOS
ntfy serve

3. スキルの通知を設定する

config/ntfy.yml を編集します：

# 是否启用通知
enabled: true

# ntfy 服务器地址
server: http://127.0.0.1          # 本地服务器
# server: https://ntfy.sh         # 官方服务器（有速率限制）

# 主题名称（手机 App 订阅的主题）
topic: mytest

# 默认优先级 (1=min, 2=low, 3=default, 4=high, 5=max)
priority: 3

4. スマートフォンでトピックを購読する

• ntfy.sh アプリ（iOS/Android）をダウンロードします
• アプリを開き、［購読］をタップします
• サーバーアドレスとトピック名を入力します

通知の形式

タスク成功：

【✅ 任务完成】
任务: execute_command
命令: echo 'Hello'
状态: 成功
返回码: 0
耗时: 0.018秒

タスク失敗：

【❌ 任务失败】
任务: execute_command
命令: invalid_command
状态: 失败
返回码: 1
耗时: 0.5秒
错误: command not found

使用例

シナリオ	優先度	例
スケジュールタスク	2	毎日のデータバックアップが完了
タスク失敗	5	コマンドの実行エラー。対応が必要
通常タスク	3	通常のスクリプト実行が完了

---

クロスプラットフォーム対応

このスキルは、異なるオペレーティングシステムを自動検出して対応します：

システム	Broker	Pool タイプ	実行ファイルのパス
Windows	Memurai	solo	Scripts/
Linux	Redis	prefork	bin/
macOS	Redis	solo/prefork	bin/

パス区切り文字や並行処理プールのタイプなどは自動的に処理されます。

Windows では、あらゆるターミナルコマンドの実行に PowerShell 構文を使用することを強く推奨します。

詳しくはクロスプラットフォーム導入ガイドを参照してください。

---

よくある質問

Q: スキル環境が設定されていない

# 使用系统 Python 创建技能虚拟环境
python scripts/setup_env.py

Q: サービスが実行中かどうかを確認するには？

Redis の確認：

# Windows
tasklist | grep -i redis
memurai-cli ping

# Linux/macOS
ps aux | grep redis
redis-cli ping

Worker の確認：

# Windows
tasklist | grep -i python

# Linux/macOS
ps aux | grep celery

Q: Redis への接続に失敗する

# Windows - 启动 Memurai（需管理员权限）
net start Memurai

# Linux
sudo systemctl start redis

# macOS
brew services start redis

Q: プロジェクト環境でコマンドを実行できない

原因： Worker はスキル環境を使用するため、プロジェクトのコマンドを見つけられません

解決策： 絶対パスまたは --cwd を使用します

# 方式1：完整路径（推荐）
# 先测试命令是否可执行
"C:\project\.venv\Scripts\aishare.exe" 002957

# 再派发任务（使用技能虚拟环境的 Python）
.venv\Scripts\python.exe scripts/dispatch.py "C:\project\.venv\Scripts\aishare.exe 002957" --delay 60 --bg

# 方式2：使用 --cwd
.venv\Scripts\python.exe scripts/dispatch.py "aishare 002957" --cwd "C:\project"

---

スキルの構成

celery-task/
├── SKILL.md                    # 本文件
├── celery_tasks/               # 任务模块
│   ├── __init__.py
│   ├── worker.py               # Celery app 和任务定义
│   └── ntfy_notifier.py        # ntfy 通知模块
├── config/                     # 配置文件
│   └── ntfy.yml                # ntfy 通知配置
├── scripts/                    # 脚本工具
│   ├── setup_env.py           # 环境设置
│   ├── worker.py              # Worker 启动
│   ├── dispatch.py            # 任务派发
│   ├── check_services.py      # 服务检查
│   └── start_monitoring.py    # 监控启动
├── references/                 # 参考文档
│   ├── platform-guide.md      # 跨平台指南
│   └── config.md              # 配置参考
└── assets/                     # 资产文件
    └── config/                # 配置模板
        ├── celery_config.py
        └── redis.conf