absurd

Absurd

当项目使用 Absurd（Postgres 原生的持久化工作流引擎），或者用户提到 absurdctl、队列、持久化任务、运行、重试、休眠任务或事件时，使用此技能。

简明心智模型

• 队列是 Absurd 表（t_、r_、c_、e_、w_）的命名空间。
• 任务是持久化的工作流实例。
• 运行是任务的一次执行尝试。
• 步骤是一个检查点。已完成步骤的结果会以 JSON 格式存储。
• 休眠任务通常在等待时间或事件。
• 事件会唤醒等待中的任务。事件负载会被缓存；首次发送的事件优先。

重要区别：

• task_id = 跨越所有执行尝试的整个工作流
• run_id = 某一次特定的执行尝试

首先：确保 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) 详细检查某个工作流或某次执行尝试

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>

找出休眠任务并唤醒一个

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 状态；重试期间，步骤外的代码可能会执行多次。