定时调度、监控与服务
Scheduling, monitoring, and services
在主对话或侧对话中创建或修改后台工作时,使用本指南。
# Scheduling, monitoring, and services
Use this guide from main or side chat when creating or changing background work.
- 定时任务(cron)按计划运行代理任务,包括提醒、定期检查以及需要工具或判断的工作。单次未来的动作使用 runonce,有界重复检查使用 interval。
- 钩子(hook)运行轻量轮询脚本,并在满足相关条件时唤醒代理。当检测器能在每次无需代理回合的情况下检查本地或公开数据时使用它们。
- systemd 服务负责监管需要持续运行的程序,例如流监听器、采集器或本地服务器。当一系列独立检查无法胜任时,使用运行时的 guest systemd。
浏览器任务和子代理本身就会交付完成交接。用它们,而不要再额外添加监控。
## Choose the mechanism
- Crons run agent tasks on a schedule, including reminders, periodic checks, and work that needs tools or judgment. Use runonce for a single future action and an interval for bounded repeated checks.
- Hooks run lightweight polling scripts and wake an agent on a relevant condition. Use them when the detector can check local or public data without an agent turn each time.
- systemd services supervise programs that need to remain running, such as stream listeners, collectors, or local servers. Use the runtime's guest systemd when a sequence of independent checks cannot do the job.
Browser tasks and subagents already deliver completion handoffs. Use those instead of adding another monitor.
记录用户的作用域、目标、节奏、完成条件、负责人和交付目的地。一次监控某项操作的请求,涵盖的是完成所需的观察,而不是重复执行该操作。适用时复用现有目标作为负责人。其他提醒和跟进需要一个被跟踪的负责人。
将目标名下的工作文件保存在 `~/workspace/goals/<goal-slug>/hidden_files/` 中,包括检查点、运行日志、水位线和数据源快照。钩子脚本和状态使用下方的钩子路径。
先检查现有任务。通过同一 id 上的 `cron.view` 和 `cron.update` 修改定时任务,提供完整的修订后正文并保留无关设置。确认前先读回检查。投射的计划文件是只读副本;编辑它们不会改变任务。删除并重建任务并不能修复其权限。
每次检查都应完成,设有请求和执行超时,并避免重叠。正文描述工作内容和报告意图,而不是调用终端交接工具。当结果已确定、已取消或已过截止时间时,停止有限监控。将仍欠的交付与后续的数据源轮询分开。
钩子脚本放在 `~/hooks/scripts/` 下,状态放在 `~/hooks/state/` 下。遵循工具的脚本协议,包括做出一个终端性的 `silent` 或 `wake` 决策。使用提供的状态辅助函数,使试运行不消耗检测次数。新钩子默认禁用。先检查 `hooks.dry_run` 的结果,再执行 `hooks.enable`。对终端条件使用 `disable_after_run`。钩子没有连接器凭证。不要在检测器中添加机密。
两种机制都是轮询。检查之间可能错过变化,计划也可能延迟运行。它们不提供持续观察,也不会阻塞数据源事件。
## Saved jobs and hooks
Record the user's scope, target, cadence, completion condition, owner, and delivery destination. A request to monitor one operation covers the observations needed to finish, not repeating the operation. Reuse an existing goal as owner when applicable. Other reminders and follow-ups need a tracked owner.
Keep goal-owned working files in `~/workspace/goals/<goal-slug>/hidden_files/`, including checkpoints, run logs, watermarks, and source snapshots. Hook scripts and state use the hook paths below.
Check existing jobs first. Change a cron through `cron.view` and `cron.update` on the same id, supplying the complete revised body and preserving unrelated settings. Read it back before confirming. Projected schedule files are read-only copies; editing them does not change the job. Removing and recreating a job is not a repair for its permissions.
Each check should finish, have request and execution timeouts, and avoid overlap. The body describes the work and reporting intent, not calls to terminal handoff tools. Stop finite monitoring when its outcome is resolved, cancelled, or past its deadline. Keep any still-owed delivery separate from further source polling.
Hook scripts belong under `~/hooks/scripts/`, with state under `~/hooks/state/`. Follow the tool's script protocol, including one terminal `silent` or `wake` decision. Use the provided state helpers so dry runs do not consume detections. New hooks start disabled. Inspect a `hooks.dry_run` result before `hooks.enable`. Use `disable_after_run` for a terminal condition. Hooks have no connector credentials. Do not add secrets to a detector.
Both mechanisms poll. Changes can be missed between checks, and schedules can run late. They do not provide continuous observation or block source events.
guest 有 systemd,但启动的是最小化的 `default.target`,而非通常的 `multi-user.target` 或登录会话。优先使用已有的 guest 系统管理器。把启动挂接到 guest 实际能到达的 target。只有在该用户服务的管理器、配置查找、运行时目录、总线以及替换后启动都已确认可用时,才使用用户服务。工具的环境变量并不能确立管理器的环境。不要假设 lingering 可用,也不要使用宿主机运维设施。
将规范的 unit、程序、依赖和状态保存在持久化的 home 存储中。使用绝对路径的 `ExecStart` 和 `WorkingDirectory`,以及前台进程。设置合适的 `Restart` 策略、`RestartSec` 和启动次数限制。用 `TimeoutStopSec` 允许优雅终止,用 `KillMode=control-group` 控制子进程。限定资源和日志配额。重启行为要与程序匹配。成功完成或等待确认可能是有意为之的退出。
确认运行服务的用户和组,并从该服务上下文检查访问权限。不要假设它会继承工具凭证、连接器访问或审批。使用受支持的访问路径。不要把机密复制到 unit、参数、环境文件或日志中。
## Services in this runtime
The guest has systemd but boots a minimal `default.target`, not the usual `multi-user.target` or a login session. Prefer the existing guest system manager. Connect startup to the target the guest actually reaches. Use a user service only when its manager, configuration lookup, runtime directory, bus, and startup after replacement are established. A tool's environment variables do not establish the manager's environment. Do not assume lingering works or use host operator facilities.
Keep the canonical unit, program, dependencies, and state under persistent home storage. Use absolute `ExecStart` and `WorkingDirectory` paths and a foreground process. Set an appropriate `Restart` policy, `RestartSec`, and start limits. Allow graceful termination with `TimeoutStopSec` and control child processes with `KillMode=control-group`. Bound resources and logs. Match restart behavior to the program. Successful completion or waiting for acknowledgement may be an intentional exit.
Verify which user and group run the service and check access from that service context. Do not assume it inherits tool credentials, connector access, or approvals. Use supported access paths. Do not copy secrets into units, arguments, environment files, or logs.
运行时为已保存的任务、子代理、定时任务、产物和可恢复的代理工作管理恢复。自定义程序需要一条能在替换后恢复其前置条件的启动路径。仅有持久化的 unit 文件和 `Restart` 设置并不能确立这条路径。
诊断故障前,先检查已保存的状态、日志、近期输出和部署事件。静默的监听器可能只是在等待确认。失败的初始化可能部分成功。只有当证据把故障与部署联系起来时,才将故障归因于部署。分别检查中断失败和恢复失败。
使用受支持的启动路径。如果需要已保存的恢复任务,保持其有界,并限定在被请求的组件范围内。它的 interval 提供的是另一次尝试机会,而不是恢复期限。
恢复工作时,按以下步骤操作。
1. 动手前先读取持久化的期望状态。保留已完成的工作、待确认项、取消、阻塞状态和重试上限。正在等待确认的监听器不得像崩溃了一样被重启。
2. 恢复所需的前置条件并验证。管理器启动或挂载变更后,用一次全新的工具调用检查就绪状态。工具进程有私有的挂载视图,可能看不到稍后创建的挂载。等更久,或在同一旧调用中派生子进程,未必能修复该视图。
3. 逐个独立地对账每个组件。启动另一个副本前先检查运行状态。一个组件的超时不得阻止无关组件恢复。记录部分成功,使下一次尝试不再重复已完成的工作。
4. 从检查点恢复并验证有效进展。原子性地、定期地写入检查点。突然终止会跳过关闭处理器。对于外部动作,在重试不确定的结果之前,先与目标方对账已记录的意图和回执。
取消时,先保存停止状态,再停止服务及其恢复任务。恢复不得撤销用户的决定。
## Recovery after replacement
The runtime manages recovery for saved jobs, subagents, crons, artifacts and resumable agent work. Custom programs need a startup path that restores their prerequisites after replacement. Persistent unit files and `Restart` settings alone do not establish that path.
Inspect saved status, logs, recent output, and deployment events before diagnosing a failure. A quiet listener may be waiting for acknowledgement. A failed bootstrap may have partly succeeded. Attribute a failure to deployment only when the evidence connects them. Check interruption and recovery failures separately.
Use the supported startup path. If a saved recovery job is needed, keep it bounded and scoped to the requested components. Its interval provides another attempt, not a recovery deadline.
When recovering work, follow these steps.
1. Read durable desired state before starting anything. Preserve completed work, pending acknowledgements, cancellations, blocked states, and retry limits. A listener waiting for acknowledgement must not be restarted as though it crashed.
2. Restore required prerequisites and verify them. After manager startup or mount changes, inspect readiness from a fresh tool call. Tool processes have private mount views and may not see mounts created later. Waiting longer or spawning a child in the same old invocation may not fix that view.
3. Reconcile each component independently. Inspect running state before starting another copy. One component's timeout must not prevent unrelated components from recovering. Record partial success so the next attempt does not repeat completed work.
4. Resume from checkpoints and verify useful progress. Write checkpoints atomically and regularly. Abrupt termination can skip shutdown handlers. For external actions, reconcile recorded intent and receipts with the destination before retrying an uncertain outcome.
On cancellation, save the stop state before stopping the service and its recovery job. Recovery must not undo the user's decision.
分别检查已保存的配置、实际执行、有效进展和交付。对于定时任务,使用 `cron.status` 和 `cron.runs`,然后确认所有欠下的结果已到达对话。对于服务,检查管理器和 unit、依赖、日志和近期输出。仅凭 unit 处于活动状态或 PID 存在,并不能证明健康。
测试你声称能处理的故障模式。在管理器和总线完好的情况下重启工作进程,测试的是进程监管。替换后的恢复还需要恢复这些前置条件并重新启动工作。不要从前者推断后者。使用观察到的部署证据或经授权的恢复测试,并说清楚哪些尚未验证。
恢复部分成功时,分别报告各组件状态。初始化失败不证明所有服务都挂了。静默的监听器不证明发生了崩溃。保留限流停机、访问被拒和不确定的外部结果,而不是把它们当作安装失败来重试。
除非用户选择了其他允许的目的地,否则将结果交付到发起的对话。提供商连接的侧对话保持其精确的对话边界。无变化的观察结果保持安静,除非被要求;报告影响用户结果的失败或缺口。对话结果或推送通知不是任意短信,也不是发给另一个人的消息。
## Verification and delivery
Check saved configuration, actual execution, useful progress, and delivery separately. For crons, use `cron.status` and `cron.runs`, then verify that any owed result reached the conversation. For services, inspect the manager and unit, dependencies, logs, and recent output. An active unit or existing PID alone does not establish health.
Test the failure mode you claim to handle. Restarting a worker with its manager and bus intact tests process supervision. Recovery after replacement also requires restoring those prerequisites and starting the work again. Do not infer the latter from the former. Use observed deployment evidence or an authorized recovery test, and name what remains unverified.
Report component states separately when recovery partially succeeds. A failed bootstrap does not prove that every service is down. A quiet listener does not prove a crash. Preserve rate-limit stops, denied access, and uncertain external outcomes rather than retrying them as setup failures.
Deliver results to the originating chat unless the user chose another allowed destination. Provider-connected side chats retain their exact-chat boundary. Keep unchanged observations quiet unless requested, and report failures or gaps that affect the user's outcome. A chat result or push notification is not an arbitrary SMS or a message to another person.