Worker Service Queue State

定义

Worker Service Queue State 是 Worker Service - Claude-Mem 摘要 中展示的一种 Worker Service 运行状态表示。它的作用是描述队列当前处于什么状态：有哪些消息还在等待处理、有哪些消息最近已经处理完成、以及哪些 session 仍然有待处理工作。

它不是业务消息本身，也不是某一条 observation 的内容结构；更准确地说，它是围绕队列与处理进度组织起来的状态快照。单条消息记录只是这个状态结构中的一个组成部分，若要单独讨论队列里的消息对象，应参见 Worker Queue Message。

在本文档中的语境

现有来源并没有给出完整的 Worker Service 调度机制、重试策略或卡住检测算法说明，而是直接给出一个 JSON 示例。因此，这个概念目前主要应理解为“Worker Service 对外展示的状态结构”而不是一套完整的处理协议。

该示例把 Worker Service 的当前运行态分成三个顶层部分：queue、recentlyProcessed、sessionsWithPendingWork。这三个部分分别对应当前队列、近期完成项，以及按 session 聚合后的待处理工作视图。

顶层组成

queue

queue 用来表示当前队列本身，其中既包含逐条消息明细，也包含若干统计指标。

它至少包含以下字段：

• messages：当前队列中的消息记录数组。
• totalPending：待处理消息数量。
• totalProcessing：正在处理中的消息数量。
• totalFailed：失败消息数量。
• stuckCount：被判定为卡住的消息数量。

示例中，这几个统计值分别是：totalPending = 5、totalProcessing = 2、totalFailed = 0、stuckCount = 1。这说明该状态不仅展示单条记录，还提供面向运维或调试的汇总视角。

recentlyProcessed

recentlyProcessed 表示近期已经处理完成的记录列表。它不是当前待处理队列，而是最近完成项的简化回看视图，用来补充“刚刚发生了什么”。

示例中的一条记录包含：

• id = 122
• session_db_id = 44
• status = "processed"
• completed_at_epoch = 1730886500000

这说明已处理记录至少会保留完成状态与完成时间，便于区分它与仍在排队或处理中但尚未完成的消息。

sessionsWithPendingWork

sessionsWithPendingWork 提供的是 session 级别的工作存在性视图，而不是逐条消息明细。它回答的问题是：当前哪些 session 下面仍然有待处理工作。

示例中该数组为 [44, 45, 46]，表示 session 44、45、46 都还有未完成的队列工作。这个结构的重点是按 session 聚合后的“是否仍有待处理项”视角，而不是说明每个 session 各自有多少条消息、每条消息是什么类型。

queue.messages 中的单条消息记录

queue.messages 保存的是单条待处理消息记录。示例中的消息对象包含如下字段：

• id: 123
• session_db_id: 45
• claude_session_id: "abc123"
• message_type: "observation"
• status: "pending"
• retry_count: 0
• created_at_epoch: 1730886600000
• started_processing_at_epoch: null
• completed_at_epoch: null

从这个例子可以看出，单条队列消息既可以关联内部的 session_db_id，也可以关联 claude_session_id。前者表现为数据库中的 session 标识，后者则表现为 Claude 会话标识；来源没有进一步解释二者之间的映射规则，但明确展示了这两种关联字段可以同时出现在同一条消息上。

message_type 在示例中是 observation，说明队列中消息带有类型信息；不过来源只给出这一个例子，未展开是否还存在其他消息类型。

`retry_count = 0`` 表明消息记录还带有重试计数，用于体现该条目已经尝试过多少次处理；但来源同样没有进一步说明重试上限或失败后如何转移状态。

状态与时间字段的关系

这个状态结构的一个关键点，是消息状态与几个 epoch 时间字段之间存在明显对应关系。

pending 消息

示例中的队列消息 status = "pending"，同时：

• started_processing_at_epoch = null
• completed_at_epoch = null

这表明对于尚未开始处理的待处理消息，可以同时没有“开始处理时间”和“完成时间”。因此，pending 至少可以覆盖“已创建、已入队、但尚未开始执行”的情形。

已处理记录

在 recentlyProcessed 中，示例记录的 status = "processed"，并且存在：

• completed_at_epoch = 1730886500000

这说明当记录处于已处理完成状态时，completed_at_epoch 会被填充。来源没有展示 processed 记录是否一定还保留 started_processing_at_epoch，因此当前只能确认：已处理记录明确具有完成时间，而待处理记录可以没有开始与完成时间。

队列统计指标的作用

queue 下的四个统计指标分别服务于不同的运行态观察目的：

• totalPending：表示当前还在等待处理的消息数量。
• totalProcessing：表示当前已经进入处理过程、但尚未完成的消息数量。
• totalFailed：表示处理失败的消息数量。
• stuckCount：表示被视为卡住的消息数量。

这四个指标合起来，使 Worker Service Queue State 不只是“消息列表”，而是一个同时提供积压、并发执行、失败和异常停滞信息的状态面板。

尤其是 stuckCount 的存在，说明该状态结构会区分普通待处理或处理中消息，与“卡住”这一更异常的情况；但来源并没有定义卡住的具体判定条件，例如超时阈值、重试次数门槛或检测频率。

细节与边界

这是状态快照，不是完整机制文档

来源给出的核心内容是一个 JSON 快照，因此我们能确认字段结构和示例值，但不能从中推出完整生命周期状态机。例如，来源没有系统说明 failed、processing、stuck 之间如何转换，也没有给出重试与恢复规则。

sessionsWithPendingWork 是聚合视图，不替代消息明细

sessionsWithPendingWork 只说明哪些 session 仍有待处理工作。它适合快速判断“哪些 session 还没清空队列”，但不能替代 queue.messages 去回答每条消息的类型、状态、重试计数或具体时间字段。

示例展示了 session 双重标识，但未解释更多语义

队列消息示例同时出现 session_db_id 与 claude_session_id，这说明状态结构能够把单条消息同时挂接到数据库 session 和 Claude session。除此之外，来源没有补充这些字段是否总是同时存在、是否允许为空、或在哪些场景只会出现其中之一。

相关条目

• Worker Service - Claude-Mem 摘要
• Worker Queue Message