Agent Bark Notify Skill：给长时间运行的 Agent 任务接上 Bark 通知

介绍我写的 Agent Bark Notify Skill：它把 Bark 推送封装成 Agent 可复用的技能，让长时间运行的多步任务主动汇报阶段进度、完成状态和阻塞原因。

写在前面

我把一个很小但很实用的需求做成了 Agent Skill：agent-bark-notify。

起因是我最近经常用 Codex 的 Goal 命令执行长时间任务。任务开始后我可能会离开电脑；虽然仍能通过 ChatGPT App 查看 Codex，但需要主动打开任务确认，不够直接。于是我做了这个 Skill，让 Codex 在关键阶段主动汇报进展。

使用下来的感觉比预想的要好，相比原来时不时去查看 Agent 执行状态，这种感觉更像是“一切尽在掌握”。不禁感叹，在原来已经有的基础设施上结合 Agent 来做一些小的修补就能实现用户体验的巨大提升。

原理、安装方法、特性

原理

这个 Skill 使用 Skill Creator 生成标准目录结构，核心逻辑分为以下几层：

Agent 先加载 SKILL.md：读取通知时机、通知级别、参数覆盖和敏感信息处理规则。
Agent 根据任务状态选择通知级别：普通进度用 passive，阻塞和失败用 timeSensitive，critical 只留给明确的紧急场景。
Agent 调用技能内置脚本：从技能目录相对执行 scripts/bark-notify.py，不用安装全局包。
脚本读取本机私有配置：Bark key 来自 ~/.config/bark-notify.env，Agent 分组和图标来自 ~/.config/bark-notify-agents.json。
脚本向 Bark server 发送请求：默认使用官方服务 https://api.day.app，也可以改成自建 Bark server。
手机端收到通知：用户根据通知内容决定是否回到任务现场处理阻塞、失败或验收结果。

安装方法

打开你的 Agent，输入以下内容：

阅读以下项目的 README，根据指引部署到本机：
https://github.com/Lumen01/agent-bark-notify

让 Agent 执行远程仓库里的安装说明之前，建议先检查 SKILL.md 和安装脚本，并固定到你审核过的 release 或 commit。安装完成后，再在全局或项目 AGENTS.md 添加一句 Prompt：

- Use the bark-notify SKILL to update the user on progress, especially when handling time-consuming tasks.

重启 Agent 后，它会在后续任务中适时报告状态或结果。第一次使用前建议先运行 --ping，再发送一条不包含敏感信息的测试通知。

细节特性

如果你想进行自定义配置，可以了解以下这些：

自定义 icon：每个 Agent 可以配置自己的图标 URL，手机通知里可以直接看出来源。
消息分组：通知可以按 Agent、项目或任务类型分组，Bark 通知列表更容易整理。
通知分级：支持 passive、active、timeSensitive、critical，不同任务状态使用不同打扰级别。
自定义铃声：支持传入 Bark sound 名称，重要任务可以使用更容易识别的提示音。
点击跳转：支持给通知附带 URL，点开通知可以直接进入任务页面、日志页面或项目地址。
复制文本：支持把指定文本放进 Bark 的 copy 字段，适合传递短命令、任务编号或排查线索。
角标数字：支持设置 badge，适合把待处理任务数同步到 iOS 图标角标。
连通性检查：内置 --ping，可以先确认 Bark server 可用，再让 Agent 发送正式通知。
本机配置保存：内置 --save-config，把 server 和 key 写入本机私有配置，避免在项目里保存密钥。

建议始终由你自己保存和输入 device key；其他非敏感配置可以交给 Agent 协助完成。

一些使用注意事项

Agent 支持范围

这个项目可以给多个 Agent 共用。我使用 Codex 比较多，其次是 Claude Code 和 OpenCode；目前在我的环境中都能按预期运行。如果你的使用场景类似，可以把它放在共享目录：

~/.agents/skills/bark-notify

然后不同 Agent 再按自己的目录规则引用它。例如 Codex 可以链接到 ~/.codex/skills/bark-notify，Claude、OpenCode 或其他 Agent 也可以使用各自对应的技能目录。

共享目录有两个好处：通知规则只维护一份；不同 Agent 可以带着自己的身份发通知。比如 Codex 的通知进入 Codex 分组，Claude 的通知进入 Claude 分组，手机上看一眼就知道是谁在汇报。

其他 Agent 也可以采用同样的组织方式，前提是它们支持读取技能目录并遵守 SKILL.md 中的规则。

Bark 官方服务还是自建服务？

Bark 有官方服务，也支持自建 server。这个 Skill 两种方式都支持：默认走 https://api.day.app，也可以通过配置把 BARK_SERVER 指向自己的服务。

选官方服务的好处是简单。你只需要安装 Bark App，拿到设备 key，配置给脚本，就能开始用。对个人使用、低频通知、非敏感内容来说，这是成本最低的路径。

选自建服务的理由主要是隐私、可控性。

Bark 通知请求里会包含通知标题、正文、分组、跳转 URL、复制文本、图标 URL、通知级别等信息。使用官方服务时，这些请求会经过官方 Bark server，再由它转交给 Apple Push Notification service。普通提醒可以接受这个路径；部署环境、内部服务名、错误摘要、机器信息这类内容，更适合走自建服务。

自建 Bark server 可以减少这部分暴露面：请求先到你自己的服务，再进入 Apple 的推送链路。iOS 推送本身仍然依赖 APNs，通知内容仍会进入 Apple 推送链路；自建 server 的主要价值是避开官方 Bark server。

我的建议是：

普通个人任务、测试通知、非敏感进度：官方服务足够方便
公司项目、内网服务、部署状态、设备维护：优先考虑自建服务
通知正文里可能出现 token、密钥、完整日志：不要发，哪怕你自建了 server

这个 Skill 也因此强调一条规则：Agent 不要把敏感配置或完整命令输出原样塞进通知里。通知写状态摘要，不写日志转储。

如果你决定自建，可以继续看后续实践：把 Bark Server 从 homelab K8s 迁移到 Cloudflare Workers。迁到自有域名可以避开官方 Bark Server，但运行平台和 iOS 推送仍分别依赖你的部署环境与 Apple APNs。

适合的任务类型

我主要会在这几类任务里使用它：

Codex Goal 这类长时间、多步骤任务
构建、测试、部署、回滚
远程服务器或设备维护
多仓库修改后的连续验证
需要人类在中途做判断的排障任务
Agent 完成后需要提醒我回来看结果的后台工作

它不适合每一步都通知。理想状态是只在阶段边界发消息：

开始执行耗时构建
测试通过
构建失败，需要修复
远程服务恢复
任务完成
等待用户确认下一步

它的目标很小但很有用：减少我主动查看任务状态的次数。

小结

agent-bark-notify 是一个很小的 Skill，但它补上了 Agent 工作流里很关键的一环：状态反馈。

以前 Agent 长时间执行任务时，我要么守在电脑前，要么过一会儿主动回来看看；现在它可以在关键节点主动告诉我进展、结果和阻塞原因。