16.2 · 运行时与工具模块（Runtime and Utility Crates）

运行时与工具模块

运行时与工具库

本章节介绍 jcode 工作空间中专用的工具库和运行时库。这些库提供了代理信号处理、嵌入向量生成、通知分发、夜间自主编排以及终端用户界面组件等离散功能。

jcode-智能体-运行时

jcode-agent-runtime 库提供了控制代理执行流程的基础类型，主要围绕中断和流式错误处理。

• 中断信号：使用 InterruptSignal（一个线程安全的原子布尔包装器）来协调 background_tool_signal 和 graceful_shutdown 请求 src/agent/interrupts.rs:162-168。
• 软中断队列：一个线程安全的 Arc<Mutex<Vec<SoftInterruptMessage>>>，允许服务器或后台任务在下一个安全的轮次边界处向代理的上下文注入消息 src/agent/interrupts.rs:7-9, 156-158。
• 软中断来源：SoftInterruptSource 对中断的来源进行分类（用户、系统或后台任务），这决定了消息在会话历史中的标记方式 src/agent/interrupts.rs:12-18。
• 远程恢复：TUI 实现了 recover_stranded_soft_interrupts，以确保在连接断开时，待处理的交错消息得以保留，并在重新连接时重新入队 src/tui/app/remote/queue_recovery.rs:134-168。

来源：src/agent/interrupts.rs:7-18, 156-168、src/tui/app/remote/queue_recovery.rs:134-168

jcode-嵌入

jcode-embedding 库使用 all-MiniLM-L6-v2 模型提供了高性能的本地嵌入向量解决方案。它利用 tract ONNX 运行时进行推理，无需外部 API 调用。

全局缓存外观

在主 jcode 库的 src/embedding.rs 中，提供了一个围绕后端的线程安全外观。

• LRU 缓存：进程级别的 EMBEDDING_CACHE_CAPACITY 设置为 128，通过对输入文本进行哈希处理，避免对相同字符串重复执行 ONNX 运行 src/embedding.rs:17-22, 151-178。
• 统计追踪：EmbedderStats 结构体追踪模型制品大小、加载次数以及平均推理延迟（毫秒级）src/embedding.rs:50-68。
• 空闲卸载：为节省系统内存，maybe_unload_if_idle 函数会在模型在可配置的时长内未被使用时，自动将其从内存中卸载 src/embedding.rs:216-218。

文本嵌入向量管线

jcode · 全局缓存外观 · 图 1

来源：src/embedding.rs:17-68, 151-178

jcode-overnight-核心

该库定义了自主"夜间"模式的数据结构和提示逻辑，允许代理在用户离开时处理长时间运行的任务。

夜间生命周期

• OvernightManifest：核心状态对象，包含 run_id、target_wake_at 以及日志、审查 HTML 和任务卡片的路径 crates/jcode-overnight-core/src/lib.rs:47-82。
• 任务卡片：结构化的 JSON 对象（OvernightTaskCard），追踪特定子任务的"之前"（问题/证据）和"之后"（变更/文件/验证）状态 crates/jcode-overnight-core/src/lib.rs:176-204。
• 自动催促：TUI 实现了 OVERNIGHT_MAX_POKES 限制（48 次），用于定期检查代理状态，并在代理停滞或提前完成任务时提供后续提示 src/tui/app/commands_overnight.rs:11-13, 48-50。

提示生成

该库包含针对夜间协调器的专用构建器：

• 协调器提示：设置"操作契约"，强调经过验证的低风险进展以及任务卡片的使用 crates/jcode-overnight-core/src/prompts.rs:89-149。
• 阶段检测：overnight_phase 根据当前时间相对于清单的状态，判断运行处于 running（运行中）、wind-down（收尾）、morning report（晨报）还是 post-wake（唤醒后）阶段 crates/jcode-overnight-core/src/prompts.rs:7-26。

夜间运行状态机

jcode · 提示生成 · 图 2

来源：src/overnight.rs:54-127、crates/jcode-overnight-core/src/lib.rs:14-33, 47-82, 204-220、crates/jcode-overnight-core/src/prompts.rs:89-149

TUI 与工具库

jcode-tui-工作空间

该库为工作空间感知的终端界面提供了专用的小部件和样式。

• 颜色支持：重新导出 jcode-tui-style 中的标准化颜色和主题，确保 TUI 中的一致性 src/tui/color_support.rs:1。
• 主题集成：提供动画组件，如 activity_indicator 和 animated_tool_color，它们会根据 TUI 的动画策略进行自适应调整 src/tui/ui_theme.rs:17-30。

jcode-tui-render

处理可视化组件的绘制和文本布局。

• 圆角框：render_rounded_box 提供了一种标准化的方式来绘制带标题的容器，包含边框和自动标题截断功能 crates/jcode-tui-render/src/lib.rs:5-43。
• 布局工具：包含 truncate_line_to_width 和 truncate_line_with_ellipsis_to_width 逻辑，这些逻辑会考虑 Unicode 字符宽度 crates/jcode-tui-render/src/lib.rs:67-156。

错误处理与工具

核心库中的 util.rs 模块提供了 format_error_chain，它会遍历 anyhow 错误原因链，生成一个包含所有嵌套失败的详细冒号分隔字符串 src/util.rs:19-38。

来源：src/embedding.rs:50-68、crates/jcode-overnight-core/src/lib.rs:47-82、src/tui/ui_theme.rs:17-30、src/util.rs:19-38