企业官网建设流程全解析

GooeyPi 是一款面向 Pi、OMP 与 Prime Agent 三大 AI 编码助手的桌面工作台，其内置的定时任务（Schedules）功能，让你轻松创建一次性与周期性 AI 自动化工作：无需值守，AI 就会在指定时间自动执行 prompt 并把结果带回会话。本篇指南带你从零开始，掌握 GooeyPi 定时任务的创建、管理与进阶玩法。

一、GooeyPi 定时任务是什么？

GooeyPi 的定时任务可以理解为一台"无人值守的 AI 执行器"：你在 ScheduledPage.tsx 对应的Scheduled（自动化台）页面里写好一条 prompt，选好时间与模型，到点后 GooeyPi 就会启动对应 harness（Pi Work / OMP Work / Prime Work）自动跑完整个任务，并记录每一次运行的结果。

它能帮你自动化这些重复性工作 🕐：

核心特点：

• ✅双模式：支持一次性（once）与周期性（rrule）两种时间规则；
• ✅每次运行留痕：运行历史完整记录状态、耗时与产出的会话；
• ✅AI 可自建任务：Prime / OMP / Pi 的 Agent 可以直接通过工具为自己创建定时任务；
• ✅多 harness 隔离：每个 harness 拥有独立的定时任务清单，互不干扰。

二、5 步创建你的第一个 GooeyPi 定时任务

打开 GooeyPi 侧边栏进入Scheduled页面，点击右上角New schedule按钮，即可打开任务编辑器。整个流程只需 5 步：

第 1 步：填写标题与 Prompt

• Title：给任务起个名字（最长 200 字符），例如Morning issue triage；
• Prompt：告诉 AI 无人值守时要做什么（最长 1MB），这是任务的核心指令。

💡 标题和 prompt 都会参与校验，prompt 若包含被禁止的 MCP 认证命令，任务会被直接拦截（状态变为 blocked）。

第 2 步：选择执行目标（Destination）

任务每次运行时"落地"到哪里，二选一：

• New session（新会话）：每次运行都在所选项目里创建一个全新会话，互不串扰，适合独立的巡检类任务；
• Existing session（已有会话）：每次运行都回到同一个会话继续对话，保留上下文，适合需要持续跟进的长线任务。

选择后需指定一个已授权的项目；若选已有会话，再从中挑一条具体会话即可。

第 3 步：设置时间（一次性 vs 周期性）

这是创建 GooeyPi 定时任务最关键的一步，两种模式按需选择：

周期性模式的配置项：

1. 频率：Hourly（每小时）/ Daily（每天）/ Weekly（每周）/ Monthly（每月）/Advanced（高级 RRULE）；
2. Every N：间隔倍数，如 Every 2 days；
3. 星期勾选：选 Weekly 时可勾选周一到周日任意组合（如工作日 MO–FR）；
4. 开始日期与本地时间：任务的首次触发基准；
5. IANA 时区：如Asia/Shanghai、America/Los_Angeles，确保跨时区部署时点准时。

编辑器内置**"Next occurrences" 实时预览**，修改时间规则后会自动列出最近 5 次触发时间，保存前就能确认节奏是否符合预期。

高级模式下可直接填写 RFC 5545 格式的 RRULE，例如工作日每天早 9 点：

FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;BYHOUR=9;BYMINUTE=0

⚠️ RRULE 会被严格校验：必须包含FREQ=，COUNT与UNTIL不能同时使用，频率不能高于每分钟一次。校验逻辑见 recurrence.ts。

第 4 步：配置执行参数（Execution）

• Model：选择本次任务使用的模型（可跟随上次选择自动填充）；
• Reasoning：推理等级（Auto / Low / Medium / High / Extra high），仅列出当前模型支持的等级；
• Fast 模式：若模型支持，可勾选优先降低延迟。

第 5 步：预览并保存

确认底部的 Next occurrences 预览无误后，点击Create schedule。创建时系统会校验：目标项目可用、模型可用、推理等级与 Fast 模式受支持，全部通过才算创建成功。

三、管理定时任务：运行、暂停、恢复与删除

创建只是开始。点击任意任务进入详情页，你可以对它做全生命周期管理：

任务状态一览：

• active：正常等待触发；
• paused：已暂停；
• completed：一次性任务执行完毕；
• blocked：因环境变化被拦截（如项目被移除、模型不支持所选推理等级）；
• Needs attention：最近一次运行失败（failed）或被中断（interrupted）时的醒目标记 🔔。

错过的时间点会补跑吗？

不会暴力补跑。GooeyPi 有一个 60 秒的宽限期（service.ts 中的DUE_GRACE_MS）：

• 若任务到期时 GooeyPi未运行（或迟到了 60 秒以上），该次触发会被标记为skipped，并自动跳到下一个触发点，避免"醒来后连补 8 次"的轰炸；
• 应用重启时，上一进程遗留的queued/running记录会被收敛为interrupted，不会永远挂起。

同时系统内置并发保护：全局最多500 个任务，同一时刻最多2 个任务并发运行，其余排队等待。

查看执行历史（Run history）

每次运行都会生成一条历史记录，详情页展示最近 8 条，每条包含：

• 状态图标（成功 / 失败 / 运行中 / 排队 / 跳过）；
• 触发方式（scheduled定时 ormanual手动）；
• 结束时间与错误信息；
• 一键打开产出会话：新会话模式的任务会以任务标题 · 日期命名会话，点击即可直接回看 AI 的完整工作过程。

运行历史自动滚动保留：每个任务最多保留 50 条、全局最多 2000 条（见 retention.ts），历史记录不会无限膨胀。

四、进阶：让 AI Agent 自己创建定时任务

GooeyPi 最强大的设计之一：定时任务不仅能由你创建，还能由 AI 自己创建。

Prime Agent：prime-work-schedules 技能

Prime Work 内置了prime-work-schedules技能（SKILL.md），Agent 可以在对话中直接调用：

• create_once(...)：创建一次性任务；
• create_recurring(...)：创建周期性任务（RRULE + 本地开始时间 + IANA 时区）；
• list / update / pause / resume / run_now / delete：全套管理能力。

比如你只需说一句"每个工作日早上 9 点帮我巡检一次 issue"，Agent 就会自己建好这条任务 🤖。

OMP 与 Pi：内置扩展工具

omp-work-schedules.ts 为 OMP Work 与 Pi Work 注册了 5 个同名工具：scheduled_tasks_list、scheduled_task_create_once、scheduled_task_create_recurring、scheduled_task_update、scheduled_task_manage。

安全边界值得注意：Agent 创建的任务只能绑定到当前项目（current_project）或当前会话（current_session），无法越权操作其他项目或 harness；所有调用经由带随机令牌的本地回环 broker 完成，渲染进程拿不到令牌（详见 docs/security.md）。

五、Prime 心跳（Heartbeat）与定时任务的区别

使用 Prime Work 时，Scheduled 页面下方还会出现Agent heartbeats区域（实现见 heartbeats.ts），它们是 Prime Agent 原生自带的心跳任务，由 Prime 运行时直接管理，GooeyPi 只做展示与暂停/恢复/停止。

如何区分该用哪个？

简单记：用户可见、长期存在的自动化用定时任务；Agent 干活期间的临时轮询用心跳。

六、macOS 后台运行：关闭窗口，任务照常触发

定时任务的执行依赖 GooeyPi 进程存活。在 macOS 上，你可以让它彻底"隐身值守" 🌙：

1. 打开Settings → General；
2. 开启关闭窗口后保持后台运行（keepRunningInBackground）——关闭窗口后应用转为菜单栏常驻，任务照常触发；
3. 可选开启登录时启动（launchAtLogin），开机即就绪。

打包版应用还支持--background启动参数，直接以无窗口后台模式运行（机制见 background.ts）。

七、定时任务常见问题 FAQ

Q1：关掉 GooeyPi 后，错过的任务会补跑吗？不会补跑。错过的触发点会被记为skipped并跳到下一个时间点，避免堆积补跑。macOS 建议开启后台常驻以获得最佳准点率。

Q2：任务显示 "Needs attention" 是什么意思？表示任务被blocked（如项目被移除、模型不支持所选推理等级或 Fast 模式）或最近一次运行failed/interrupted。详情页会给出具体原因，处理后可点 Resume 恢复。

Q3：一次性任务执行完会变成什么状态？自动变为completed，不再触发，但仍保留在列表中可查看历史与产出会话。

Q4：同一个会话上安排了很多任务会互相冲突吗？不会。GooeyPi 对同一会话内置了串行锁（executor.ts 中的withSessionLock），针对同一会话的运行会依次排队，保证上下文不互相污染。

Q5：定时任务最多能建多少条？全局上限 500 条，标题最长 200 字符，prompt 最长 1MB。

八、关键源码导读

想深入理解实现，推荐按这条路径阅读：

• 界面层：ScheduledPage.tsx —— 任务列表、编辑器、执行历史 UI；
• 核心服务：service.ts —— 任务的创建、暂停、恢复与触发调度；
• 时间规则：recurrence.ts —— RRULE 校验、时区换算与触发点展开；
• 执行器：executor.ts —— 新会话/已有会话两种执行路径与会话锁；
• 历史保留：retention.ts —— 50/2000 条的滚动清理策略；
• Agent 侧扩展：omp-work-schedules.ts、prime-work-schedules/SKILL.md。

结语

GooeyPi 定时任务把"让 AI 到点自动干活"变得像设置一个闹钟一样简单：一次性任务处理单点需求，周期性任务接管长期重复劳动，Agent 还能按需自建任务。配合 macOS 后台常驻，它真正做到了无人值守的 AI 自动化工作。现在打开 Scheduled 页面，创建你的第一条定时任务吧 ⏰