AS AgentScopeAPI 手册 / API Reference
类class io.agentscope.builder.web.coord 2.x

JdbcCoordinationStore

public class JdbcCoordinationStore implements CoordinationStore
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:45–762

JDBC Coordination 存储，负责持久化与读取数据。位于 io.agentscope.builder.web.coord 包，实现 CoordinationStore。核心成员包括 tryAcquireTurnLease、heartbeatTurnLease、releaseTurnLease、getTurnLease、listExpiredTurnLeases、requestTurnInterrupt。

JDBC-backed CoordinationStore using the builder catalog DataSource / JPA schema.

Registered as the default bean from BuilderConfig; operators can replace it by declaring another CoordinationStore bean (e.g. Redis).

构造器摘要Constructor Summary

构造器Constructor说明Description
public JdbcCoordinationStore(CoordLeaseEntityRepository leaseRepository, CoordHitlTicketEntityRepository hitlRepository, CoordWorkItemEntityRepository workRepository, CoordWorkerHeartbeatEntityRepository workerRepository, TransactionTemplate transactionTemplate)
初始化 `JdbcCoordinationStore` 实例。
Creates a new instance.

方法摘要Method Summary

方法Method说明Description
public Optional<LeaseHandle> tryAcquireTurnLease(String sessionId, String ownerId, String instanceId, Duration ttl)
执行 `tryAcquireTurnLease` 方法。
Performs the try acquire turn lease operation.
public boolean heartbeatTurnLease(String sessionId, String instanceId, Duration ttl)
执行 `heartbeatTurnLease` 方法。
Performs the heartbeat turn lease operation.
public boolean releaseTurnLease(String sessionId, String instanceId)
执行 `releaseTurnLease` 方法。
Performs the release turn lease operation.
public Optional<LeaseHandle> getTurnLease(String sessionId)
获取 `getTurnLease`。
Returns the turn lease.
public List<LeaseHandle> listExpiredTurnLeases(long nowMillis)
列出 `listExpiredTurnLeases`。
Lists the expired turn leases.
public void requestTurnInterrupt(String sessionId, String reason)
执行请求轮次中断相关操作。
Performs the request turn interrupt operation.
public void requestFencedTurnInterrupt(String sessionId, String reason, String fenceToken)
执行 `requestFencedTurnInterrupt` 方法。
Performs the request fenced turn interrupt operation.
public Optional<String> consumeTurnInterrupt(String sessionId)
设置消费轮次中断。
Performs the consume turn interrupt operation.
public Optional<TurnInterruptRequest> consumeTurnInterruptRequest(String sessionId)
设置消费轮次中断请求。
Performs the consume turn interrupt request operation.
public boolean tryAcquireFireLease(String deploymentId, String fireWindow, String instanceId, Duration ttl)
执行 `tryAcquireFireLease` 方法。
Performs the try acquire fire lease operation.
public HitlTicket putHitlTicket(HitlTicket ticket)
设置该参数。
Performs the put hitl ticket operation.
public Optional<HitlTicket> getHitlTicket(String sessionId, String toolUseId)
获取 `getHitlTicket`。
Returns the hitl ticket.
public Optional<HitlTicket> getHitlTicket(HitlDecisionFence fence)
获取 `getHitlTicket`。
Returns the hitl ticket.
public Optional<HitlResolution> resolveHitlTicket(HitlDecisionFence fence, String resolutionStatus, long decisionVersion, boolean allow, String denyMessage, long resolvedAt)
解析 `resolveHitlTicket`。
Performs the resolve hitl ticket operation.
public Optional<HitlResolution> expireHitlTicket(String sessionId, String toolUseId, long expiredAt)
执行 `expireHitlTicket` 方法。
Performs the expire hitl ticket operation.
public boolean markHitlContinuationReady(HitlDecisionFence fence)
设置该参数。
Performs the mark hitl continuation ready operation.
public void deleteHitlTicket(String sessionId, String toolUseId)
删除 `deleteHitlTicket`。
Deletes the hitl ticket.
public void deleteHitlTicketsBySession(String sessionId)
删除 `deleteHitlTicketsBySession`。
Deletes the hitl tickets by session.
public long deleteResolvedHitlTicketsBefore(long expiresAtCutoff)
删除 `deleteResolvedHitlTicketsBefore`。
Deletes the resolved hitl tickets before.
public List<HitlTicket> listExpiredHitlTickets(long nowMillis)
列出 `listExpiredHitlTickets`。
Lists the expired hitl tickets.
public WorkItemRecord enqueueWork(String sessionId, String environmentId, String ownerId)
执行 `enqueueWork` 方法。
Performs the enqueue work operation.
public Optional<WorkItemRecord> claimWork(String environmentId, String workerId, long timeoutMs) throws InterruptedException
执行 `claimWork` 方法。
Performs the claim work operation.
public void ackWork(String leaseId, String workerId, String workDir)
执行 `ackWork` 方法。
Performs the ack work operation.
public void stopWork(String leaseId)
停止 `stopWork`。
Stops the work.
public void heartbeatWork(String leaseId)
设置该参数。
Performs the heartbeat work operation.
public Optional<WorkItemRecord> getWork(String leaseId)
获取 `getWork`。
Returns the work.
public List<WorkItemRecord> listWork(String environmentId, String statusFilter)
列出 `listWork`。
Lists the work.
public WorkStats workStats(String environmentId)
设置该参数。
Performs the work stats operation.
public void workerHeartbeat(String workerId, String capabilitiesJson)
执行工作进程心跳相关操作。
Performs the worker heartbeat operation.
public Map<String, Long> workerHeartbeats()
返回 `workerHeartbeats` 结果。
Returns the worker heartbeats.
public int pendingWorkCount()
返回 `pendingWorkCount` 结果。
Returns the pending work count.
public Optional<SandboxReadyMeta> getSandboxReady(String sessionId)
获取沙箱就绪。
Returns the sandbox ready.
public void clearSandboxReady(String sessionId)
清空沙箱就绪。
Clears the sandbox ready.

构造器详情Constructor Detail

JdbcCoordinationStore

public JdbcCoordinationStore(CoordLeaseEntityRepository leaseRepository, CoordHitlTicketEntityRepository hitlRepository, CoordWorkItemEntityRepository workRepository, CoordWorkerHeartbeatEntityRepository workerRepository, TransactionTemplate transactionTemplate)

初始化 JdbcCoordinationStore 实例。

Creates a new instance.

参数Parameters
名称Name类型Type说明Description
leaseRepositoryCoordLeaseEntityRepositorylease 仓库（类型 `CoordLeaseEntityRepository`）。The lease repository.
hitlRepositoryCoordHitlTicketEntityRepositoryhitl 仓库（类型 `CoordHitlTicketEntityRepository`）。The hitl repository.
workRepositoryCoordWorkItemEntityRepositorywork 仓库（类型 `CoordWorkItemEntityRepository`）。The work repository.
workerRepositoryCoordWorkerHeartbeatEntityRepository工作进程仓库（类型 `CoordWorkerHeartbeatEntityRepository`）。The worker repository.
transactionTemplateTransactionTemplate事务模板（类型 `TransactionTemplate`）。The transaction template.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:55–66

方法详情Method Detail

tryAcquireTurnLease

public Optional<LeaseHandle> tryAcquireTurnLease(String sessionId, String ownerId, String instanceId, Duration ttl)

执行 tryAcquireTurnLease 方法。

Performs the try acquire turn lease operation.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
ownerIdString所有者标识（类型 `String`）。The owner id.
instanceIdString实例标识（类型 `String`）。The instance id.
ttlDuration存活时间（类型 `Duration`）。The ttl.
返回Returns Optional<LeaseHandle>
返回可选。Returns optional.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:68–103

heartbeatTurnLease

public boolean heartbeatTurnLease(String sessionId, String instanceId, Duration ttl)

执行 heartbeatTurnLease 方法。

Performs the heartbeat turn lease operation.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
instanceIdString实例标识（类型 `String`）。The instance id.
ttlDuration存活时间（类型 `Duration`）。The ttl.
返回Returns boolean
返回布尔值，表示判断结果。Returns a boolean result.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:105–114

releaseTurnLease

public boolean releaseTurnLease(String sessionId, String instanceId)

执行 releaseTurnLease 方法。

Performs the release turn lease operation.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
instanceIdString实例标识（类型 `String`）。The instance id.
返回Returns boolean
返回布尔值，表示判断结果。Returns a boolean result.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:116–122

getTurnLease

public Optional<LeaseHandle> getTurnLease(String sessionId)

获取 getTurnLease。

Returns the turn lease.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
返回Returns Optional<LeaseHandle>
返回可选。Returns optional.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:124–131

listExpiredTurnLeases

public List<LeaseHandle> listExpiredTurnLeases(long nowMillis)

列出 listExpiredTurnLeases。

Lists the expired turn leases.

参数Parameters
名称Name类型Type说明Description
nowMillislong当前时间毫秒（类型 `long`）。The now millis.
返回Returns List<LeaseHandle>
返回列出。Returns list.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:133–141

requestTurnInterrupt

public void requestTurnInterrupt(String sessionId, String reason)

执行请求轮次中断相关操作。

Performs the request turn interrupt operation.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
reasonString原因（类型 `String`）。The reason.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:143–147

requestFencedTurnInterrupt

public void requestFencedTurnInterrupt(String sessionId, String reason, String fenceToken)

执行 requestFencedTurnInterrupt 方法。

Performs the request fenced turn interrupt operation.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
reasonString原因（类型 `String`）。The reason.
fenceTokenStringfence 令牌（类型 `String`）。The fence token.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:149–156

consumeTurnInterrupt

public Optional<String> consumeTurnInterrupt(String sessionId)

设置消费轮次中断。

Performs the consume turn interrupt operation.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
返回Returns Optional<String>
返回可选。Returns optional.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:200–204

consumeTurnInterruptRequest

public Optional<TurnInterruptRequest> consumeTurnInterruptRequest(String sessionId)

设置消费轮次中断请求。

Performs the consume turn interrupt request operation.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
返回Returns Optional<TurnInterruptRequest>
返回可选。Returns optional.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:206–237

tryAcquireFireLease

public boolean tryAcquireFireLease(String deploymentId, String fireWindow, String instanceId, Duration ttl)

执行 tryAcquireFireLease 方法。

Performs the try acquire fire lease operation.

参数Parameters
名称Name类型Type说明Description
deploymentIdString部署标识（类型 `String`）。The deployment id.
fireWindowStringfire Window（类型 `String`）。The fire window.
instanceIdString实例标识（类型 `String`）。The instance id.
ttlDuration存活时间（类型 `Duration`）。The ttl.
返回Returns boolean
返回布尔值，表示判断结果。Returns a boolean result.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:264–295

putHitlTicket

public HitlTicket putHitlTicket(HitlTicket ticket)

设置该参数。

Performs the put hitl ticket operation.

参数Parameters
名称Name类型Type说明Description
ticketHitlTicketticket（类型 `HitlTicket`）。The ticket.
返回Returns HitlTicket
返回HitlTicket。Returns hitl ticket.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:297–340

getHitlTicket

public Optional<HitlTicket> getHitlTicket(String sessionId, String toolUseId)

获取 getHitlTicket。

Returns the hitl ticket.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
toolUseIdString工具使用标识（类型 `String`）。The tool use id.
返回Returns Optional<HitlTicket>
返回可选。Returns optional.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:342–350

getHitlTicket

public Optional<HitlTicket> getHitlTicket(HitlDecisionFence fence)

获取 getHitlTicket。

Returns the hitl ticket.

参数Parameters
名称Name类型Type说明Description
fenceHitlDecisionFencefence（类型 `HitlDecisionFence`）。The fence.
返回Returns Optional<HitlTicket>
返回可选。Returns optional.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:352–365

resolveHitlTicket

public Optional<HitlResolution> resolveHitlTicket(HitlDecisionFence fence, String resolutionStatus, long decisionVersion, boolean allow, String denyMessage, long resolvedAt)

解析 resolveHitlTicket。

Performs the resolve hitl ticket operation.

参数Parameters
名称Name类型Type说明Description
fenceHitlDecisionFencefence（类型 `HitlDecisionFence`）。The fence.
resolutionStatusStringresolution 状态（类型 `String`）。The resolution status.
decisionVersionlong决策版本（类型 `long`）。The decision version.
allowbooleanallow（类型 `boolean`）。The allow.
denyMessageString拒绝消息（类型 `String`）。The deny message.
resolvedAtlong已解析 At（类型 `long`）。The resolved at.
返回Returns Optional<HitlResolution>
返回可选。Returns optional.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:367–409

expireHitlTicket

public Optional<HitlResolution> expireHitlTicket(String sessionId, String toolUseId, long expiredAt)

执行 expireHitlTicket 方法。

Performs the expire hitl ticket operation.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
toolUseIdString工具使用标识（类型 `String`）。The tool use id.
expiredAtlong已过期 At（类型 `long`）。The expired at.
返回Returns Optional<HitlResolution>
返回可选。Returns optional.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:411–434

markHitlContinuationReady

public boolean markHitlContinuationReady(HitlDecisionFence fence)

设置该参数。

Performs the mark hitl continuation ready operation.

参数Parameters
名称Name类型Type说明Description
fenceHitlDecisionFencefence（类型 `HitlDecisionFence`）。The fence.
返回Returns boolean
返回布尔值，表示判断结果。Returns a boolean result.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:436–455

deleteHitlTicket

public void deleteHitlTicket(String sessionId, String toolUseId)

删除 deleteHitlTicket。

Deletes the hitl ticket.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
toolUseIdString工具使用标识（类型 `String`）。The tool use id.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:457–461

deleteHitlTicketsBySession

public void deleteHitlTicketsBySession(String sessionId)

删除 deleteHitlTicketsBySession。

Deletes the hitl tickets by session.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:463–467

deleteResolvedHitlTicketsBefore

public long deleteResolvedHitlTicketsBefore(long expiresAtCutoff)

删除 deleteResolvedHitlTicketsBefore。

Deletes the resolved hitl tickets before.

参数Parameters
名称Name类型Type说明Description
expiresAtCutofflong过期 At Cutoff（类型 `long`）。The expires at cutoff.
返回Returns long
返回数值结果。Returns a numeric result.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:469–473

listExpiredHitlTickets

public List<HitlTicket> listExpiredHitlTickets(long nowMillis)

列出 listExpiredHitlTickets。

Lists the expired hitl tickets.

参数Parameters
名称Name类型Type说明Description
nowMillislong当前时间毫秒（类型 `long`）。The now millis.
返回Returns List<HitlTicket>
返回列出。Returns list.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:475–481

enqueueWork

public WorkItemRecord enqueueWork(String sessionId, String environmentId, String ownerId)

执行 enqueueWork 方法。

Performs the enqueue work operation.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
environmentIdString环境标识（类型 `String`）。The environment id.
ownerIdString所有者标识（类型 `String`）。The owner id.
返回Returns WorkItemRecord
返回WorkItemRecord。Returns work item record.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:483–497

claimWork

public Optional<WorkItemRecord> claimWork(String environmentId, String workerId, long timeoutMs) throws InterruptedException

执行 claimWork 方法。

Performs the claim work operation.

参数Parameters
名称Name类型Type说明Description
environmentIdString环境标识（类型 `String`）。The environment id.
workerIdString工作进程标识（类型 `String`）。The worker id.
timeoutMslong超时 Ms（类型 `long`）。The timeout ms.
返回Returns Optional<WorkItemRecord>
返回可选。Returns optional.
抛出Throws
  • InterruptedException 可能抛出 `InterruptedException`。Thrown when the operation cannot be completed.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:499–519

ackWork

public void ackWork(String leaseId, String workerId, String workDir)

执行 ackWork 方法。

Performs the ack work operation.

参数Parameters
名称Name类型Type说明Description
leaseIdStringlease 标识（类型 `String`）。The lease id.
workerIdString工作进程标识（类型 `String`）。The worker id.
workDirStringwork 目录（类型 `String`）。The work dir.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:542–559

stopWork

public void stopWork(String leaseId)

停止 stopWork。

Stops the work.

参数Parameters
名称Name类型Type说明Description
leaseIdStringlease 标识（类型 `String`）。The lease id.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:561–572

heartbeatWork

public void heartbeatWork(String leaseId)

设置该参数。

Performs the heartbeat work operation.

参数Parameters
名称Name类型Type说明Description
leaseIdStringlease 标识（类型 `String`）。The lease id.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:574–584

getWork

public Optional<WorkItemRecord> getWork(String leaseId)

获取 getWork。

Returns the work.

参数Parameters
名称Name类型Type说明Description
leaseIdStringlease 标识（类型 `String`）。The lease id.
返回Returns Optional<WorkItemRecord>
返回可选。Returns optional.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:586–590

listWork

public List<WorkItemRecord> listWork(String environmentId, String statusFilter)

列出 listWork。

Lists the work.

参数Parameters
名称Name类型Type说明Description
environmentIdString环境标识（类型 `String`）。The environment id.
statusFilterString状态过滤器（类型 `String`）。The status filter.
返回Returns List<WorkItemRecord>
返回列出。Returns list.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:592–601

workStats

public WorkStats workStats(String environmentId)

设置该参数。

Performs the work stats operation.

参数Parameters
名称Name类型Type说明Description
environmentIdString环境标识（类型 `String`）。The environment id.
返回Returns WorkStats
返回WorkStats。Returns work stats.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:603–624

workerHeartbeat

public void workerHeartbeat(String workerId, String capabilitiesJson)

执行工作进程心跳相关操作。

Performs the worker heartbeat operation.

参数Parameters
名称Name类型Type说明Description
workerIdString工作进程标识（类型 `String`）。The worker id.
capabilitiesJsonString能力 JSON（类型 `String`）。The capabilities json.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:626–642

workerHeartbeats

public Map<String, Long> workerHeartbeats()

返回 workerHeartbeats 结果。

Returns the worker heartbeats.

返回Returns Map<String, Long>
返回映射。Returns map.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:644–652

pendingWorkCount

public int pendingWorkCount()

返回 pendingWorkCount 结果。

Returns the pending work count.

返回Returns int
返回数值结果。Returns a numeric result.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:654–658

getSandboxReady

public Optional<SandboxReadyMeta> getSandboxReady(String sessionId)

获取沙箱就绪。

Returns the sandbox ready.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
返回Returns Optional<SandboxReadyMeta>
返回可选。Returns optional.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:660–678

clearSandboxReady

public void clearSandboxReady(String sessionId)

清空沙箱就绪。

Clears the sandbox ready.

参数Parameters
名称Name类型Type说明Description
sessionIdString会话标识（类型 `String`）。The session id.
源码Source io/agentscope/builder/web/coord/JdbcCoordinationStore.java:680–684

继承成员Inherited Members

继承自Members inherited from CoordinationStore
WORK_STALE_THRESHOLD
基于官方固定版本源码静态生成Generated from pinned official sources · Python 2.0.11 · Java 2.0.4
签名与文档为静态抽取；如有疑问请以源码为准。Signatures and docs are extracted statically; verify against the source when in doubt.