用途
iii-dead-letter-queues 用于检查和重新投递（redrive）那些已经耗尽所有重试次数的队列任务。它适用于处理失败的队列任务、调试处理错误，或实现重试策略的场景。该技能对应 SQS DLQ、RabbitMQ dead-letter exchanges 等同类机制。
主要能力
- 任务在达到 max_retries 上限后，经过指数退避（backoff_ms * 2^attempt）进入 DLQ。
- 每个 DLQ 条目保留原始负载、最后错误、时间戳和任务元数据。
- 通过内置的 iii::queue::redrive 函数或 iii trigger CLI 命令进行重投。
- 重投会将尝试计数器重置为零，让任务获得全新的重试周期。
- 支持在 Builtin 和 RabbitMQ 适配器上使用 DLQ。
使用方式
技能涉及以下 iii 原语：
trigger({ function_id: 'iii::queue::redrive', payload: { queue } })：重投指定队列的所有 DLQ 任务。trigger({ function_id: 'iii::queue::status', payload: { queue } })：检查队列和 DLQ 状态。iii trigger --function-id='iii::queue::redrive' --payload='{"queue":"name"}'：CLI 重投命令（属于引擎二进制文件的一部分）。--timeout-ms：CLI 标志，用于设置触发超时（默认 30 秒）。queue_configs（位于 iii-config.yaml）：配置 max_retries 和 backoff_ms。
常见代码模式包括：
await iii.trigger({ function_id: 'iii::queue::redrive', payload: { queue: 'payment' } })— 通过 SDK 重投。iii trigger --function-id='iii::queue::redrive' --payload='{"queue": "payment"}'— 通过 CLI 重投。iii trigger --function-id='iii::queue::redrive' --payload='{"queue": "payment"}' --timeout-ms=60000— 使用自定义超时。- 重投返回
{ queue: 'payment', redriven: 12 }，表示重放任务的数量。 - 在 RabbitMQ UI（http://localhost:15672）中检查
iii.__fn_queue::{name}::dlq.queue。
参考实现提供 JavaScript（../references/dead-letter-queues.js）、Python（../references/dead-letter-queues.py）和 Rust（../references/dead-letter-queues.rs）版本，涵盖检查 DLQ 状态、通过 SDK 和 CLI 重投失败任务，以及配置重试行为。
适用场景
- 处理失败的队列任务。
- 调试处理错误。
- 实现重试策略。
- 构建管理端点，调用 iii::queue::redrive 进行运维控制。
- 使用 iii::queue::status 在重投前后检查 DLQ 深度。
- 在开发/测试中使用较低的重试次数以更快暴露失败。
- 在生产环境使用 RabbitMQ 时，通过管理 UI 进行详细的消息检查。
- 考虑构建在 DLQ 深度阈值上触发的告警函数。
限制与边界
- 并非每个队列失败都需要手动 DLQ 干预。
- 始终先调查并部署修复，再执行重投——盲目重投会重复失败。
- 队列处理模式（入队、并发、FIFO）应优先使用 iii-queue-processing。
- 队列配置（重试、退避、适配器）应优先使用 iii-engine-config。
- 函数注册和触发器应优先使用 iii-functions-and-triggers。
- 仅当主要问题是检查或重投失败任务时，才使用本技能。
- 不得将本技能作为无关任务的通用回退方案。
- 当有更具体的 iii 技能更合适时，不得应用本技能。
- 应用示例前始终验证环境和安全约束。
架构说明
队列消费者处理任务失败。引擎按指数退避重试，直到 max_retries。一旦耗尽，消息移入 DLQ。操作者检查失败、部署修复，然后重投 DLQ 以重放所有失败任务。
引擎配置
队列的 max_retries 和 backoff_ms 在 iii-config.yaml 的 queue_configs 下按队列设置。完整注释配置参考见 ../references/iii-config.yaml。
最佳实践
- 先调查失败、部署修复，再重投。
- 将 DLQ 深度作为运维告警信号进行监控。
- 根据失败容忍度在 queue_configs 中设置 max_retries 和 backoff_ms。