heartbeat-cron

Heartbeat 创建器

通过结构化访谈、测试运行和优化循环，为 murmur 创建精心编写的 HEARTBEAT.md 文件。

背景

Murmur 是一个精简的调度程序。它会读取 HEARTBEAT.md 文件，按计划将文件内容发送给 Claude，并对响应进行分类：

• HEARTBEAT_OK — 无需报告（静默）
• ATTENTION: ... — 需要人工关注（记录并在 TUI 中显示）

Murmur 无法通知用户。 它只运行提示词并记录结果。如果用户需要通知（Slack、Telegram、推送），HEARTBEAT.md 本身必须包含发送步骤。心跳就是完整的流程：收集数据 → 做出判断 → 执行操作 → 发送通知。

每次心跳都是无状态的。 每次运行都会启动一个全新的 Claude 会话，不会记住之前的运行。对于需要追踪随时间变化情况的工作流（价格变动、上次检查时间戳），请使用工作区中的文件作为简单的状态存储（例如 last-price.txt、tracking-state.json）。

睡眠/唤醒行为。 机器进入睡眠时，守护进程会暂停，不会触发定时任务。唤醒后，逾期任务会立即运行，但多次错过的运行会合并为一次补执行（而非每个错过的间隔各运行一次）。这对于心跳类任务是正确的：你需要检查当前状态，而不是重放错过的检查。如果用户需要可靠的定时调度，请建议他们关闭机器的睡眠功能（参见 README 中的 FAQ）。

HEARTBEAT.md 格式

每个心跳都是一个可选包含 YAML frontmatter 块的 Markdown 文件。frontmatter 中的值优先于 config.json。

---
interval: 1h # or cron: "0 9 * * 1-5" (pick one)
# tz: America/New_York  # timezone for cron (default: local system tz)
# timeout: 15m          # max run time (default: 5m)
# agent: claude-code    # "claude-code" (default), "codex", or "pi"
# model: opus           # model hint passed to the agent
# maxTurns: 50          # cap agent iterations per run (default: 99)
# name: My Heartbeat
# description: What this heartbeat does
# session: my-session   # pi-specific: reuse a named browser session
# sandbox: workspace-write  # codex-specific: "read-only", "workspace-write", or "danger-full-access"
# networkAccess: false  # codex-specific: allow outbound network in workspace-write sandbox
# permissions: skip      # skip permission checks (only "skip" supported in frontmatter)
---
Your prompt here...

注意：

• interval 或 cron — 只能使用其中一个，不能同时使用。间隔：15m、1h、6h、1d。Cron：标准的 5 字段表达式。
• permissions: "skip" 是 frontmatter 中唯一支持的权限值。对于拒绝列表，请使用 config.json。
• murmur init 会生成一个预先填好这些字段的模板。

工作流

0. 预检

开始之前，确认已安装 murmur：

which murmur

• 已找到 → 继续访谈。
• 未找到 → 通过 Homebrew 安装：

  brew install t0dorakis/murmur/murmur
  

  如果无法使用 Homebrew，请从源代码安装：

  git clone https://github.com/t0dorakis/murmur.git
  cd murmur && bun install && bun run build
  # Then add ./murmur to PATH
  

你也可以立即通过标志创建工作区框架：

murmur init {path} --interval 30m
murmur init {path} --cron "0 9 * * 1-5" --timeout 15m
murmur init {path} --template github-digest   # Use a starter template

每个仓库包含多个心跳 — 使用 --name 在 heartbeats/ 目录中创建心跳：

murmur init {path} --name issue-worker --interval 30m
murmur init {path} --name deploy-monitor --cron "0 9 * * 1-5"

这会在工作区中创建 heartbeats/<name>/HEARTBEAT.md。所有心跳都以仓库根目录作为当前工作目录。命名心跳可以与根目录下的 HEARTBEAT.md 同时使用。

1. 访谈

使用 AskUserQuestion 进行有针对性的访谈。每次提一到两个问题，并根据之前的回答逐步深入。

第 1 轮 — 目标：

询问他们想要自动化什么。如果他们还不确定或正在探索，请阅读 references/examples.md，从代码／代码仓库、研究／情报、运维／基础设施、个人／创意等类别中寻找灵感。根据他们的情况推荐示例。

第 1b 轮 — 工具发现：

深入了解具体细节前，先检查用户的目标是否需要安装现有工具之外的工具。进行网页搜索，寻找可能有帮助的 CLI、MCP 服务或 Agent 技能。

浏览器工具 — 许多有价值的 heartbeat 都需要与真实网站交互（查看价格、监控页面、登录门户）。Claude 内置的 WebFetch 适用于简单的静态页面，但对于使用 JavaScript 渲染、包含登录流程或具有反机器人措施的网站，则需要真实的浏览器：

• agent-browser — 面向 AI Agent 的无头浏览器 CLI。开箱即可与 Claude Code 配合使用。
• pi-browser — pi 的浏览器扩展。与 agent: pi 配合使用。

其他工具 — 搜索网页，查询："{user's goal}" CLI tool 或 "{user's goal}" MCP server，也可以查看 skills.sh 上的社区技能。例如：

• 日历访问 → Google Calendar MCP 或 pi-google-calendar 扩展
• Slack／Discord 消息投递 → skills.sh 上的 webhook 技能
• GitHub 操作 → 确保已安装 gh CLI

告诉用户你找到的内容，并建议安装能提升 heartbeat 能力的工具。

第 2 轮 — 具体细节：

根据他们的目标深入了解具体情况：

• 需要哪些工具／API／命令？（gh、curl、特定 URL、API 密钥）
• 工作区目录是什么？
• 应该多久运行一次？有两个选项：
  • 间隔 — 固定频率：15m、1h、6h、1d
  • Cron — 精确计划：0 9 * * 1-5（工作日早上 9 点）、*/30 * * * *（每 30 分钟）
  • 如果他们选择 cron，请询问时区（默认为本地系统时区）
• heartbeat 是否需要超过默认的 5 分钟超时时间？（例如，长时间运行的任务可设置 timeout: 15m）
• 对模型有偏好吗？（默认使用 Agent 的默认模型；也可设置 model: opus、model: sonnet 等）
• Agent 选择：claude-code（默认）运行 Claude Code CLI；codex 运行 OpenAI Codex CLI（使用沙盒策略）；pi 运行 pi Agent（支持浏览器扩展）

第 3 轮 — 消息投递：

这一点至关重要。询问他们希望如何接收结果。选项：

• 写入工作区中的文件（最简单，也是不错的默认选项）
• 通过 webhook 发布到 Slack／Discord
• 通过 Telegram bot API 发送
• 创建 GitHub issue／评论
• 通过 ntfy.sh 推送通知
• 仅使用 ATTENTION 响应（用户查看 TUI／日志）

提醒他们：murmur 只是一个调度器，不会转发任何内容。如果他们希望收到通知，heartbeat 本身必须负责发送通知。

第 3b 轮 — 凭据（如有需要）：

如果消息投递或数据源需要令牌／webhook：

• 可使用工作区 .env 中的环境变量（Bun 会自动加载这些变量）
• 敏感值应放在 .env 中，并在 heartbeat 中以 $VAR_NAME 的形式引用

2. 起草

编写 HEARTBEAT.md 文件。规则：

• 包含 YAML frontmatter 块，至少设置调度频率（interval 或 cron）。根据访谈内容，按需添加 timeout、model 或其他字段。
• 不要添加关于 HEARTBEAT_OK / ATTENTION 的说明——运行时会自动注入这些内容
• 明确写出每个步骤——Claude 在不同心跳之间不会保留记忆
• 对于变更检测工作流（降价、新增项目、状态变更），请添加读取和写入工作区状态文件的步骤（例如，last-price.txt、tracking-state.json）
• 写出带有实际值的准确命令（不能留下 {placeholder}）
• 如果用户需要通知，请添加发送步骤
• 内容聚焦——每个心跳只负责一项任务
• 对机密信息使用 $VAR_NAME

对于单心跳工作区，将文件放在 {workspace}/HEARTBEAT.md；对于多心跳代码仓库，将文件放在 {workspace}/heartbeats/{name}/HEARTBEAT.md。

3. 测试

运行一次心跳以进行验证：

murmur beat {workspace_path}
# Or for a named heartbeat:
murmur beat {workspace_path} --name {name}

向用户展示结果和输出。

4. 评估

询问用户：“这是否符合你的预期？”

• 否 → 根据反馈完善 HEARTBEAT.md，再次测试。重复此过程，直到用户满意。
• 是 → 继续注册。

5. 注册

使用 murmur 注册工作区，让守护进程了解该工作区：

1. 运行 murmur init {absolute_workspace_path}——此命令会自动将工作区注册到 ~/.murmur/config.json（包含 { path, lastRun: null }）。如果 HEARTBEAT.md 已存在，则跳过创建文件，但仍会注册工作区。
2. 验证注册情况：murmur workspaces list
3. 调度频率、超时、模型和其他设置都放在 HEARTBEAT.md 的 frontmatter 中——无需为这些设置编辑 config.json。
4. 仅当需要设置 permissions.deny 列表时，才直接编辑 ~/.murmur/config.json（frontmatter 仅支持 permissions: skip）。
5. 告知用户启动守护进程：
   • murmur start——在前台运行并显示 TUI（按 q 退出，按 d 脱离）
   • murmur start --detach——在后台运行（使用 murmur watch 重新连接）

规则

• 最终的 HEARTBEAT.md 中不能留下 {placeholder} 值
• 宣布完成前，始终使用 murmur beat 进行测试
• 始终请用户评估测试结果
• 如果心跳需要用户尚未安装的工具，告知用户需要安装哪些工具
• 一个心跳 = 一项任务。同一代码仓库中有多个自动化任务时，使用 heartbeats/ 目录并搭配 --name。
• 调度频率建议：运行状态监测用 15m，活跃开发工作用 1h，摘要/研究用 6h–1d。如果用户需要在特定时间运行，请使用 cron（例如，工作日早晨使用 0 9 * * 1-5）。