开发工具代码编辑器数据科学【免费下载链接】positronPositron, a next-generation data science IDE项目地址https://gitcode.com/gh_mirrors/po/positron点击查看免费下载导读本文围绕 Positron 数据科学 IDE 的 supervisor 扩展中ExecutionQueue这一数据模型展开讲解 KallichoreJupyter 内核网关与 supervisor如何用一张“当前活动执行 待执行队列”的快照来描述一个会话的执行状态。读完本文你将掌握active、length、pending三个字段的确切语义与默认行为、如何用 TypeScript 构造该对象、它在重连繁忙会话与连接状态播报中的实际用途以及stop_on_error与执行队列之间的联动关系。1. ExecutionQueue 在项目中的位置ExecutionQueue是 Kallichore 客户端库中的一个 API 模型位于 extensions/positron-supervisor/src/kcclient/docs/ExecutionQueue.md。该目录下的客户端代码完全由 OpenAPI Generator 的typescript-axios模式从 Kallichore API 定义自动生成参见 extensions/positron-supervisor/src/kcclient/README.md因此这份文档本质上描述的是 Kallichore 服务端通过 HTTP API 暴露的会话执行队列数据结构。它的使用场景非常聚焦作为 ActiveSession 模型的一个字段execution_queue随会话状态一起下发给客户端让客户端无需轮询内核即可了解会话当前正在执行什么、还有多少请求在排队。2. 字段语义active、length、pending原文档以属性表形式给出了该模型的三个字段这里结合生成代码 extensions/positron-supervisor/src/kcclient/api.ts#L313-L329 逐一展开字段类型必填语义activeobject可选optional当前正在被求值的执行请求若会话空闲则不存在undefinedlengthnumber必填待执行队列pending 队列中的条目数量pendingArrayobject必填待执行请求的队列几点值得注意的细节active是可选字段且默认 undefined会话空闲时没有正在执行的请求因此该字段可以缺席只有当会话处于 busy 状态时才可能携带具体值。从源码看active的实际内容是一个 Jupyter 消息对象详见下文第 4 节。length与pending.length应保持一致length描述的是“pending 队列中的条目数量”即待执行请求数并不包含正在执行的active请求。因此一个繁忙会话若还有 3 个请求排队其execution_queue形如{ active: {...}, length: 3, pending: [{...}, {...}, {...}] }。pending的每个元素是object它们是尚未被内核处理的执行请求对象与ExecuteRequest见 extensions/positron-supervisor/src/kcclient/docs/ExecuteRequest.md描述的“一次代码执行请求”在概念上对应。从整体建模看execution_queue描述的是会话执行流水线的“工作队列快照”active是当前正在被内核求值的请求pending是排队等候的请求length是排队数量。3. 构造与使用示例原文档给出了 TypeScript 构造示例完整形式如下import { ExecutionQueue } from ./api; const instance: ExecutionQueue { active, // 当前正在被求值的执行请求可选空闲时为 undefined length, // 待执行队列中的条目数量 pending, // 待执行请求队列 };在仓库中一个符合该模型的最小真实样例出现在单元测试 extensions/positron-supervisor/src/test/restoredSessionEnv.test.ts#L71execution_queue: { length: 0, pending: [] },它表示一个空闲会话没有正在执行的请求active缺省、队列长度为 0、没有待执行请求。该测试用于验证“重连恢复会话时回放启动环境变量”的行为说明构造ActiveSession时execution_queue是必填字段ActiveSession接口中声明为execution_queue: ExecutionQueue;参见 api.ts#L81即使是空队列也必须显式提供。4. 源码中的实际用途重连繁忙会话与连接状态播报ExecutionQueue不只是文档中的静态模型它在 supervisor 中有两处关键的运行时消费4.1 重连繁忙会话时重放“忙碌”状态在 extensions/positron-supervisor/src/KallichoreSession.ts#L1562-L1601 中当客户端重连到一个状态为Busy的会话时会读取execution_queue.active将其视为一个JupyterMessageJupyter 消息据此合成一条status类型的 IOPub 消息execution_state: busy发送给前端const activeExecution this._activeSession?.execution_queue.active as JupyterMessage; if (activeExecution) { const kernelStatus: JupyterKernelStatus { execution_state: busy }; const statusMessage: JupyterMessage { header: { msg_id: status-replay-${createUniqueId()}, session: activeExecution.header.session, msg_type: JupyterMessageType.Status, ... }, channel: JupyterChannel.IOPub, parent_header: activeExecution.header, ... }; this._messages.onKernelStatus(statusMessage, kernelStatus); }这正是active字段被设计为object而非强类型化的原因服务端直接存放内核消息客户端按 Jupyter 协议将其还原为原始消息体。这里可以推断active在运行时实际承载的是 Jupyter 的execute_request消息携带header、channel、content等字段其header.session被用于关联合成消息。4.2 连接状态句子的播报在 extensions/positron-supervisor/src/KallichoreInstances.ts#L1001-L1015 中describeSessionConnectionSentence根据execution_queue.length生成面向用户的本地化描述const queueLength session.execution_queue?.length ?? 0; if (queueLength 0) { const queueLabel queueLength 1 ? vscode.l10n.t(1 pending execution) : vscode.l10n.t({0} pending executions, queueLength); ... }当队列长度为 1 时播报 “1 pending execution”大于 1 时播报 “N pending executions”并结合connected字段区分“已连接客户端”“未连接客户端”两种场景。这里用可选链?.容错说明客户端在处理远端会话数据时对execution_queue缺失的情况保持健壮。5. 执行队列与 stop_on_error 的联动执行队列的行为不仅体现在状态快照上还受执行请求参数控制。Kallichore 的ExecuteRequest模型见 ExecuteRequest.md定义了一个与队列直接相关的开关stop_on_error若为 true默认出错时中止执行队列若为 false即使当前请求失败排队的执行请求仍会被继续处理。在 supervisor 中该参数由错误处理策略映射而来KallichoreSession.ts#L939stop_on_error: errorBehavior positron.RuntimeErrorBehavior.Stop,也就是说用户选择“出错即停止”策略时一次失败执行会清空/中止剩余 pending 队列选择继续策略时pending 中的请求会照常逐个执行。这从侧面印证了pending队列的语义它是会话级串行执行流水线的排队区而stop_on_error决定了出错时流水线是整体中止还是继续推进。6. 会话执行流水线的完整视图综合以上模型与源码一个会话的执行流水线可以概括为客户端向内核发送execute_request请求进入会话的待执行队列pending内核开始处理时该请求成为active同时pending移除该条目、length递减执行期间会话状态为BusyActiveSession.execution_queue中的active携带当前请求消息执行完成且无剩余排队请求时active变为 undefined、length为 0会话回到Idle若执行出错且stop_on_error为 true剩余pending请求被中止。supervisor 侧还通过waitForIdle()KallichoreSession.ts#L1694-L1707监听状态事件等待会话空闲用于重连后的就绪标记等场景而重连时execution_queue.active的存在与否正是判断“会话当前是否有未完成执行”的直接依据。7. 与相邻模型的关系ExecutionQueue处于会话状态模型的中间层与其相邻的模型共同构成完整的会话视图ActiveSession通过execution_queue字段持有执行队列同时通过statusStatus.md、idle_seconds、busy_seconds描述会话运行状态ExecuteRequest描述单个执行请求的内容与参数code、silent、store_history、stop_on_error、timeout_seconds是进入队列的“请求体”ExecutionHistoryEntry记录会话已完成的执行输入/输出/错误/时间戳与pending/active形成“已完成、执行中、待执行”三段式视图ExecuteReply对应执行请求的回复status为ok或error是stop_on_error判断错误的中介。8. 使用前提与注意事项本客户端为生成代码根据 kcclient/README.mdExecutionQueue接口及本文档均来自 OpenAPI 定义自动生成仓库明确提示“不要直接编辑此目录下的文件”如需修改应改动 Kallichore 仓库中的 OpenAPI 定义kallichore.json并运行scripts/regen-api.sh重新生成。active为可选项编写消费方代码时应先判断active是否存在空闲会话无此字段避免直接读取属性报错length与pending为必填但远端数据不可靠时建议仍用?.容错参考KallichoreInstances.ts的session.execution_queue?.length ?? 0写法。active的内容形态虽然类型标注为object从 supervisor 的重连逻辑可以推断其运行时形态为 Jupyter 消息对象含header、channel、content、buffers等字段按 Jupyter 协议消费即可。参考文件速览模型文档extensions/positron-supervisor/src/kcclient/docs/ExecutionQueue.md接口定义extensions/positron-supervisor/src/kcclient/api.ts#L313-L329宿主模型extensions/positron-supervisor/src/kcclient/docs/ActiveSession.md执行请求模型extensions/positron-supervisor/src/kcclient/docs/ExecuteRequest.md客户端说明extensions/positron-supervisor/src/kcclient/README.md运行时消费 extensions/positron-supervisor/src/KallichoreSession.ts、extensions/positron-supervisor/src/KallichoreInstances.ts测试样例extensions/positron-supervisor/src/test/restoredSessionEnv.test.ts赞分享开发工具代码编辑器数据科学【免费下载链接】positronPositron, a next-generation data science IDE项目地址https://gitcode.com/gh_mirrors/po/positron点击查看免费下载相关推荐Positron Supervisor 的 ExecutionError 模型Kallichore 执行错误的数据结构详解Positron Supervisor 的 ExecutionError 模型Kallichore 执行错误的数据结构详解 导读 ExecutionError开发工具代码编辑器数据科学Positron Supervisor 执行历史模型 ExecutionHistoryEntry 深度解析字段语义、截断机制与源码实现Positron Supervisor 执行历史模型 ExecutionHistoryEntry 深度解析字段语义、截断机制与源码实现 导读本文以 Posi开发工具代码编辑器数据科学OpenProject 6.1.6 会话过期安全修复解析从发布公告到会话生命周期源码实现OpenProject 6.1.6 会话过期安全修复解析从发布公告到会话生命周期源码实现 output文章 /output文章 output文章 Ope后端前端项目管理企业应用协同办公上一篇HyperFrames 构图 Schema 合规审查实践用确定性规则为 Agent 生成的 HTML 视频把脉下一篇从安装到源码用 ZCode 的 ai-elements Message 组件套件构建 AI 聊天界面创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考