absurd

Absurd

プロジェクトでPostgresネイティブの永続ワークフローエンジンであるAbsurdを使用している場合、またはユーザーが**absurdctl**、キュー、永続タスク、実行、再試行、スリープ中のタスク、イベントについて言及した場合に、このスキルを使用します。

簡単なメンタルモデル

• キューはAbsurdのテーブル（t_、r_、c_、e_、w_）の名前空間です。
• タスクは永続ワークフローのインスタンスです。
• 実行はタスクの1回の実行試行です。
• ステップはチェックポイントです。完了したステップの結果はJSONとして保存されます。
• スリープ中のタスクは通常、時間またはイベントを待っています。
• イベントは待機中のタスクを起動します。イベントペイロードはキャッシュされ、最初のイベント発行が優先されます。

重要な違い：

• task_id = すべての試行を通したワークフロー全体
• run_id = 特定の実行試行1回

まず、absurdctlが動作することを確認する

absurdctlがPATH上にない場合は、リポジトリのチェックアウト内にいるか確認し、そうであれば次を使用します。

export PATH="$PWD:$PATH"

Absurdの接続情報の優先順位は次のとおりです。

--database > ABSURD_DATABASE_URL > PGDATABASE > postgresql://localhost/absurd

URI以外の接続では、PGHOST、PGPORT、PGUSER、PGPASSWORDも使用されます。

デフォルトのデバッグワークフロー

ソースを調べる前に、まずabsurdctlで状態を確認してください。通常、最初にアプリケーションコードを読む必要はありません。

ユーザーからワークフローの調査や修正に**absurdctl**を使うよう明示的に依頼された場合は、rgやソースコードの調査から始めず、まずその指示に従ってください。

ユーザーがタスクのデバッグを希望する場合は、次のコマンドを順番に実行します。

1) キューを確認する

absurdctl list-queues

2) 該当する可能性が高いキューの最近のアクティビティを調べる

absurdctl list-tasks --queue=default --limit=20

注意：

• --limitを省略すると、list-tasksはデフォルトで50行を表示します。
• 有用なステータス：pending、running、sleeping、completed、failed、cancelled。

3) 失敗したタスクまたはスリープ中のタスクに絞り込む

absurdctl list-tasks --queue=default --status=failed --limit=20
absurdctl list-tasks --queue=default --status=sleeping --limit=20

4) ワークフローまたは試行を1つ選んで詳細を調べる

absurdctl dump-task --task-id=<task-id>
absurdctl dump-task --run-id=<run-id>

dump-taskは最も重要な調査コマンドです。次のような情報を表示します。

• タスク名、パラメーター、ヘッダー
• 再試行の設定と試行回数
• チェックポイントに保存されたステップの状態
• 待機／イベント／スリープの状態
• 最終結果または失敗

よくある状態の考え方

タスクがfailedの場合

1. dump-task --task-id=<task-id>
2. 失敗の内容と、最後に成功したチェックポイントを確認します。
3. 必要に応じて、--run-idで最新の試行を調べます。
4. タスク名を使って、タスクの実装をコード内で検索します。
5. その後で、再試行するか判断します。

タスクがsleepingの場合

1. dump-task --task-id=<task-id>
2. 待機理由を確認します。
   • 指定のタイムスタンプまでスリープ中
   • イベント名を待機中
3. イベントを待機中で、ユーザーがタスクの再開を希望している場合は、そのイベントを発行します。

タスクがrunningの場合

1. dump-task --task-id=<task-id>
2. 既存のチェックポイントを確認して、どこまで進んだかを調べます。
3. ユーザーがワーカーの停止を疑っている場合は、ワーカープロセス／アプリケーションログも調べます。

ワーカーについて

ワーカーを起動または変更する必要があると決めつけないでください。

• 起動したタスクがpendingからsleeping、running、またはcompletedに移行する場合、ワーカーはすでに稼働しています。
• タスクがpendingのままの場合は、そのキューのワーカーが実際に稼働しているか調べます。
• タスクの状態からワーカーの問題が疑われる場合、またはユーザーがコードの変更を求めている場合に限り、Python／TypeScriptランタイムの詳細を調べます。

実装を確認する必要がある場合

タスク名が分かったら、コードベース内でその登録箇所を検索します。

TypeScript／JavaScript：

rg -n "registerTask\(|name:\s*['\"]<task-name>['\"]" .

Python：

rg -n "register_task\(|@.*register_task|['\"]<task-name>['\"]" .

タスクがイベントを待機している場合は、イベント名も検索します。

よくある操作

タスクを起動する

文字列には-P key=valueを使用し、型付きJSON値には-P key:=jsonを使用します。

absurdctl spawn-task my-task -q default -P foo=bar
absurdctl spawn-task my-task -q default -P count:=42 -P enabled:=true
absurdctl spawn-task my-task -q default -P user.name=Alice -P user.age:=30

ユーザーがすでにJSONオブジェクトを持っている場合は、--paramsを使用します。

absurdctl spawn-task my-task -q default --params '{"foo":"bar","count":42}'

失敗したタスクを再試行する

absurdctl retry-task <task-id>
absurdctl retry-task <task-id> --max-attempts 5
absurdctl retry-task -q default <task-id> --spawn-new

ガイダンス：

• 引数なしのretry-taskは既存のタスクを再試行します。
• --spawn-newは元の入力を使って新しいタスクを作成します。
• 再試行する前に、まず失敗の原因を把握してください。

タスクをキャンセルする

absurdctl cancel-task <task-id>
absurdctl cancel-task -q default <task-id>

イベントを発行して待機中のタスクを起動する

absurdctl emit-event order.completed -q default -P orderId=123
absurdctl emit-event approval.granted:42 -q default -P approved:=true

イベントペイロードを構造化JSONにする場合：

absurdctl emit-event shipment.packed:42 -q default --payload '{"trackingNumber":"XYZ"}'

スキーマのセットアップ／マイグレーション

空のデータベースまたは管理されたデータベースで使用するか、ユーザーから明示的に依頼された場合に使用してください。

absurdctl init
absurdctl schema-version
absurdctl migrate
absurdctl create-queue default

安全な運用ルール

状態を変更するコマンドには注意してください。ユーザーが明確に希望していない限り、共有データベースや本番データベースで次のコマンドを確認せずに実行するのは避けてください。

• init
• migrate
• create-queue
• drop-queue
• cleanup
• cancel-task
• retry-task
• emit-event
• spawn-task

環境が不明確な場合は、操作しても安全なデータベース／キューを確認してください。

コピーしてすぐ使える便利な手順

default の最新の失敗をデバッグする

absurdctl list-queues
absurdctl list-tasks --queue=default --status=failed --limit=20
absurdctl dump-task --task-id=<task-id>

スリープ中のタスクを探して、1 つを起動する

absurdctl list-tasks --queue=default --status=sleeping --limit=20
absurdctl dump-task --task-id=<task-id>
absurdctl emit-event <event-name> -q default -P key=value

タスクを起動して再現し、その後調査する

absurdctl spawn-task my-task -q default -P foo=bar
absurdctl list-tasks --queue=default --task-name=my-task --limit=5
absurdctl dump-task --task-id=<task-id>

ユーザーが「タスクを起動してデバッグして」と言った場合の最短手順：

absurdctl spawn-task my-task -q default -P foo=bar
absurdctl list-tasks --queue=default --task-name=my-task --limit=5
absurdctl dump-task --task-id=<task-id>
# then either:
absurdctl emit-event <event-name> -q default -P key=value
# or:
absurdctl retry-task <task-id>

追加リファレンス

• オプションの詳細については、absurdctl <command> --help を使用してください。
• タスクが分かったら、通常は dump-task --task-id から始めるのが最適です。
• チェックポイント付きのステップ結果は永続化される JSON 状態です。ステップ外のコードは、リトライ中に複数回実行されることがあります。