8.1 · 后台运行器与调度器（Ambient Runner and Scheduler）

后台运行器与调度器

环境运行器与调度器

相关源文件

本章引用的主要源码文件：

• docs/CRATE_OWNERSHIP_BOUNDARIES.md
• scripts/check_dependency_boundaries.py
• scripts/warning_budget.txt
• src/ambient.rs
• src/ambient/directives.rs
• src/ambient/manager.rs
• src/ambient/paths.rs
• src/ambient/persistence.rs
• src/ambient_runner.rs
• src/ambient_scheduler.rs
• src/ambient_tests.rs
• src/channel.rs
• src/memory_graph.rs
• src/notifications.rs
• src/safety.rs
• src/tool/ambient.rs
• src/tool/ambient/tests.rs
• src/tui/test_harness.rs
• tests/e2e/main.rs

环境运行器与调度器系统为 jcode 提供了主动的后台代理能力。它管理"环境周期"（Ambient Cycles）的生命周期——这些自主代理会话负责执行后台工作，例如代码维护、主动重构和记忆维护——同时确保资源使用保持在提供商速率限制之内。

AmbientRunnerHandle 与生命周期

AmbientRunnerHandle 是后台操作的主要编排点。它管理一个长期运行的循环，该循环根据调度计划、资源可用性或外部事件触发环境周期 src/ambient_runner.rs:1-4。

AmbientStatus 生命周期

运行器会经历 AmbientStatus 中定义的多个状态 src/ambient.rs:70-83：

• Idle（空闲）：运行器处于活动状态，但正在等待下一个调度时间或手动触发 src/ambient.rs:72-72。
• Running（运行中）：当前有一个活动的代理会话正在执行环境周期，detail 字符串描述了当前任务 src/ambient.rs:73-75。
• Scheduled（已调度）：特定任务已排队，等待未来的时间戳（next_wake）执行 src/ambient.rs:76-78。
• Paused（已暂停）：运行器暂时停止，通常是因为用户会话处于活动状态 src/ambient.rs:79-81。
• Disabled（已禁用）：通过配置关闭了环境模式 src/ambient.rs:82-82。

实例保护

为防止竞态条件和重复的后台工作，jcode 使用 AmbientLock。这个基于文件的锁确保对于给定的 jcode 目录，只有一个环境运行器实例处于活动状态 src/ambient/persistence.rs:18-18。

来源： src/ambient.rs:70-83、src/ambient/persistence.rs:18-18、src/ambient_runner.rs:1-4

AdaptiveScheduler 与 EWMA

AdaptiveScheduler 管理后台任务的执行时机，以防止耗尽大语言模型（LLM）提供商的配额。它维护一个 UsageLog 来跟踪 Token 消耗 src/ambient/scheduler.rs:1-2。

资源感知的唤醒间隔

调度器通过评估使用历史和提供商速率限制来计算间隔。系统使用指数加权移动平均（EWMA）来根据近期消耗预测未来容量。

间隔计算逻辑

调度器通过评估以下因素确定等待时间：

1. 使用历史：每分钟 Token 使用量的滚动平均值。
2. 退避乘数：一个内部乘数，在遇到速率限制命中时会进行调整，以防止激进的重新尝试。

来源： src/ambient/scheduler.rs:1-2、src/ambient.rs:12-12

ScheduledItem 优先级队列

任务以 ScheduledItem 结构体表示，并持久化存储于环境队列中 src/ambient.rs:114-133。

优先级与目标定位

项目按 Priority（优先级）（Low（低）、Normal（正常）、High（高））排序 src/ambient.rs:87-91。任务可以通过 ScheduleTarget（调度目标）定位：

• Ambient（环境）：唤醒后台代理以处理任务 src/ambient.rs:98-99。
• Session（会话）：将提醒发送回特定的交互式会话 ID src/ambient.rs:100-101。
• Spawn（派生）：从父会话派生出一个新会话 src/ambient.rs:102-103。

系统映射：调度流程

下图将逻辑上的调度概念桥接到实现它们的代码实体。

环境任务调度实体映射图

来源： src/ambient.rs:86-133、src/ambient.rs:170-189、src/ambient/persistence.rs:18-18、src/ambient/scheduler.rs:1-2

VisibleCycleContext 交接

当环境周期需要用户干预或过渡到可见状态时，它会使用 VisibleCycleContext src/ambient.rs:36-39。

上下文持久化

上下文被保存到 ~/.jcode/ambient/visible_cycle.json src/ambient.rs:42-46。这允许 TUI 客户端"附加"到后台进程，并向用户展示代理的当前状态、系统提示和初始消息 src/ambient.rs:48-54。

周期完成

在周期结束时，代理调用 end_ambient_cycle 工具 src/tool/ambient.rs:144-147。该工具填充一个 AmbientCycleResult，其中包含工作摘要、记忆修改以及下一次调度唤醒的请求 src/ambient.rs:148-160、src/tool/ambient.rs:198-210。

来源： src/ambient.rs:33-66、src/tool/ambient.rs:20-41、src/tool/ambient.rs:144-210

外部交互与通知

环境周期由 SafetySystem 监控，并可以通过多种渠道发送通知 src/notifications.rs:50-54。

通知分发

NotificationDispatcher 通过以下方式发送周期摘要和权限请求：

• ntfy.sh：向移动设备推送通知 src/notifications.rs:174-184。
• 桌面端：使用系统特定的紧急程度发送本地通知 src/notifications.rs:187-197。
• 电子邮件：发送包含批准/拒绝按钮的富 HTML 电子邮件，用于处理权限请求 src/notifications.rs:201-210。

用户指令

用户可以通过 UserDirective 向后台代理提供指令 src/ambient/directives.rs:15-16。这些指令在环境生命周期期间被加载和处理，以影响代理行为 src/ambient/directives.rs:15-16。

环境交互架构图

来源： src/notifications.rs:50-54、src/notifications.rs:82-103、src/ambient/directives.rs:15-16、src/tool/ambient.rs:108-114、src/safety.rs:128-133