Pushary: human-in-the-loop for AI agents

Pushary：AI Agent 的人在回路

为 AI Agent 提供推送通知和人在回路功能。从手机上批准。
开始使用  ·  技能目录  ·  报告错误

从这里开始

无需注册即可试用审批 → 连接已打开的手机页面 → 批准或拒绝 → 查看 Agent 继续执行或停止。 此浏览器演示使用轮询和临时状态，不提供真实推送，也不使用生产账本。

你想构建的内容	从这里开始
为编码 Agent 提供通知和提问功能	查看下方的设置说明
在 Vercel AI SDK 中强制执行工具审批	可运行的 AI SDK 示例
根据人工决策进行分支处理的 LangGraph 工作流	可运行的 LangGraph 示例
其他 Agent 框架	所有 Pushary 集成
Agent 应在何时停下来询问人员，以及如何在任何框架中添加这一步	pushary-human-in-the-loop 技能

此技能和适配器采用 MIT 许可证。托管式手机推送需要 Pushary 账户；若要为你自己的用户嵌入审批功能，则需要 Partner 访问权限。 这两个框架示例也可在本地运行，使用模拟回答且无需凭据。

如果 Pushary 对你有所帮助，请为此仓库点星。 想要提供帮助？欢迎提交公开问题和补丁。

---

Pushary 可让你的编码 Agent 向手机发送任务更新并询问你如何决策。受支持的宿主钩子还会在操作执行前强制要求审批。

托管式推送需要付费的 Pushary 方案。MCP 提问和通知适用于任何兼容客户端；强制审批则取决于宿主集成。

工作原理

AI Agent  ->  MCP Protocol  ->  Pushary API  ->  Push Notification  ->  Your Phone

Pushary 是一个MCP 服务，可将你的 AI 编码 Agent 连接到推送通知。Agent 通过模型上下文协议调用 Pushary 的工具，你便能在任何设备上即时收到通知。

三种提问类型——是/否确认、多项选择和自由文本输入。Agent 会根据具体情况选择合适的类型。

包含丰富上下文的通知——Agent 可以在详细信息页面中附上文件更改、错误详情和建议的后续步骤；点击通知即可查看。

Agent 身份标识——运行多个 Agent 时，每条通知都会显示发起提问的 Agent，让你始终清楚自己正在回应谁。

权限钩子——将 Claude Code 的工具审批提示转为推送通知，让你可以通过手机批准或拒绝。

---

个人设置：手机优先

在 Agent 的终端中运行配对设置：

npx pushary@latest setup

在手机上安装 Pushary，扫描二维码或打开打印出的链接，比较指纹并批准。随后，设置会为所选 Agent 配置工具、受支持的钩子和技能。无需先复制 API 密钥。个人账户需要付费方案。现有凭据会重复使用。

验证设置：

npx pushary@latest doctor

请 Agent 回答一个无害的测试问题。确认预期设备收到了问题，并且答案返回到同一任务。

仅针对 Hermes：

npx pushary@latest setup --agents hermes

这会将原生插件写入 ~/.hermes/plugins/pushary，并通过 hermes plugins enable pushary 和 hermes config set 启用。之后使用 hermes gateway restart 重启 Hermes。该插件提供通知、提问、等待、取消、提醒和范围工具，以及 Partner 注册和客户提问工具。其参数使用 snake_case；请使用 Hermes 技能，而不是 MCP 参数名称。原生审批传输会保留 Hermes 的会话和常驻审批。

Mac 刘海和其他答题界面

安装 Pushary for Mac，使用同一个个人账户登录，并在应用中连接 Agent。刘海界面提供确认、选择、文本和问题集控件，并支持键盘操作。请保持应用运行，以便维持在线状态和消息送达；先在那里验证一个无害的问题，再测试离开 Mac 时的手机回退方式。

界面	答题方式
移动设备	在应用中确认、选择和输入文本。受支持的确认通知可在锁屏界面批准或拒绝；任意选项和文本问题需要打开应用。
Mac 刘海	接收已登录账户的问题，包括通过键盘作答；Partner 客户从手机连接 Mac 后，也可接收他们的问题。
Slack	配置好集成和接收者后，可使用按钮、选项菜单和文本模态窗口。
浏览器	提供决策页面回退；启用权限后还会发送浏览器通知。

消息送达方式遵循你的设置和在线状态。push_first 根据在线状态处理，push_only 每次都请求推送，notify_only 将决策保留在当前客户端中，terminal_only 则避免推送。仅 API 调用成功，并不能证明设备已显示请求。

Partner 设置：面向你自己的客户

个人配对连接的是你本人，即操作员。Partner 集成通过范围受限的连接链接为你应用的每位客户注册，并使用客户的稳定 ID 来发送决策。客户使用移动端注册流程；不要将他们的审批发送到你的个人 Mac 收件箱，也不要共享操作员 API 密钥。

请先阅读 Partner 集成指南，再查看 Mastra Agent 示例、AI SDK 示例或 LangGraph 示例。工具可选择确认、选择或文本操作。批准操作与提供答案是不同的操作；文本答案“是”并不代表允许执行另一个工具。

手动备用方案

对于需要手动配置 MCP 的客户端，请在 Pushary 控制面板中获取密钥并进行配置：

{
  "mcpServers": {
    "pushary": {
      "url": "https://pushary.com/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

请妥善保管密钥。如果客户端支持 skills.sh，请使用 npx skills add Pushary/pushary-skill 安装技能。手动配置 MCP 可提供协作式提问和通知；要强制执行审批，则需要使用受支持的宿主钩子／运行时集成。

Claude Code 用户也可以将此仓库安装为插件：

/plugin marketplace add Pushary/pushary-skill
/plugin install pushary

该方式会从环境变量中读取 PUSHARY_API_KEY。请选择一种安装方式：如果在通过 CLI 安装的 Claude 钩子基础上再安装插件，钩子可能会运行两次。切换安装方式前，请使用 npx pushary@latest clean。

插件会通过 npx 启动每个钩子，而这对于需要向手机实时传送回复预览的钩子来说太慢了，因此插件不会安装该钩子。如需实时预览，请改用 npx pushary@latest setup 安装。Setup 会将每个钩子安装为本地命令。

---

设置：Lovable

Lovable 是托管式应用构建器，因此无需本地安装（不适用 npx skills add）。你需要在 Lovable 的界面中连接 MCP 服务，然后将技能粘贴到 Lovable 的 Knowledge 中，让 Agent 自动使用它。

1. 连接 MCP 服务。 在 Lovable 中，前往 Settings -> Connectors -> Personal connectors（付费 Lovable 套餐），点击 New MCP server，将 URL 设为 https://pushary.com/api/mcp/mcp，选择 Bearer token，然后粘贴你的 API 密钥（pk_xxx.xxx）。

2. 将技能添加到 Knowledge。 Lovable 无法通过 npx 安装技能，因此请将技能指南粘贴到 Settings -> Knowledge。使用精简版 SKILL-LITE.md 作为来源。这样，Lovable Agent 就会在构建完成时通知你，并在进行高风险更改前征求你的同意，无需你每次都发出提示。

Lovable 仅支持通知和提问（由于没有权限钩子，因此无法强制执行审批）。完整操作指南：Lovable 指南。

---

设置：Claude Chat 和 Cowork

对于 Claude Chat 或 Claude Code，请使用 Pushary for Claude。在 Chat 中，打开 Customize > Plugins > Add > Add marketplace，添加 https://github.com/Pushary/claude-plugin，然后安装 Pushary for Claude。在 Claude Code 中，运行 /plugin marketplace add Pushary/claude-plugin，然后运行 /plugin install pushary@pushary-claude-plugin。

对于 Cowork，现有的 Pushary for Cowork 插件仍可使用。将 https://github.com/Pushary/cowork-plugin 添加为市场，然后安装 Pushary for Cowork。Cowork 也支持在 Settings > Cowork 下设置常驻指令。现有插件、市场和 pushary-cowork 技能标识符均保持不变。

这两个插件包均使用公开 OAuth 连接器和同一个共享技能。在 Chat 或 Cowork 中，打开插件的 Connectors 选项卡连接 Pushary；在 Claude Code 中，使用 /mcp 连接。然后使用手机或 Mac 上同一个 Pushary 账户登录。这两个插件包都不需要 CLI 或 API 密钥。

如果找不到连接器，请在 Customize > Connectors > Add custom connector 下添加 https://pushary.com/api/mcp/mcp，并将 OAuth Client ID 和 Secret 字段留空。在对话中启用 Pushary，提出一个无害的测试问题，并确认 Claude 返回了你的答案。

这些插件包可提供提问和通知，但不会安装原生权限钩子。如需 Claude Code 审批钩子，请使用上文的 Claude Code 设置。每个应用请选择一种安装方式，以免重复添加 Pushary 连接器。Claude 完整指南。

---

工具

此技能可指导使用以下 MCP 工具：

工具	描述
send_notification	发送推送通知，可附带丰富上下文（文件更改、错误、后续步骤）
ask_user	通过推送向用户提问，支持是/否、选择题或自由文本
wait_for_answer	长轮询，等待用户回答问题
cancel_question	取消不再相关的待处理问题
list_sessions	以只读方式查看正在运行的 Agent 会话和待处理问题
propose_scope	确定运行范围：文件 glob（在支持的主机上强制执行），或在运行不更改文件时记录承诺

完整工具文档（含参数、示例和使用指南）请参阅 skills/pushary/SKILL.md。

人机交互

Agent 可以通过推送向你征求决定，并等待你的回答：

Agent: "Which auth strategy should I use?"
  Options: JWT tokens / Session cookies / OAuth2 + PKCE
  -> push to your phone

You: tap "JWT tokens"

Agent: proceeds with JWT implementation

支持三种问题类型：

• Confirm - 是/否二选一
• Select - 从 2-6 个选项中选择
• Input - 自由文本回答

从工具结果中读取 answered、status 和 handoffAction（或 nextAction）。仅按指示轮询；将问题交给另一个界面前，先取消仍在进行的问题，并遵从最终生效的回答。过期和等待时间遵循服务端策略。沉默不代表批准，迟到的回复也无法重新启动已结束的 Agent 轮次。

软件包

软件包	仓库	描述
pushary	npm	Pushary 命令行工具：设置、权限钩子和诊断工具。也以 @pushary/agent-hooks 发布，是同一个软件包
hermes-plugin-pushary	PyPI	Hermes Agent 原生插件

兼容的 Agent

适用于任何支持 skills.sh 或 Model Context Protocol 的 Agent：

• Claude Code（MCP + 权限钩子）
• Claude Cowork（自定义连接器 + 技能上传）
• Hermes Agent（原生插件或 MCP）
• Cursor（MCP）
• Windsurf（MCP）
• Lovable（MCP 连接器 + 通过 Knowledge 添加技能）
• OpenAI Codex（MCP）
• 其他支持远程 MCP 服务的客户端

发布 MCP 注册表条目

合并 server.json 并不会发布它。MCP 注册表每个版本只提供一条记录，因此在此处编辑后，必须将新版本推送到注册表，内容才会生效；否则所有 Agent 读取的仍是旧文本。

常规流程：在 server.json 中提升 version，合并到 main，然后同步公开技能镜像。其发布工作流会发布新的注册表条目。

发布工作流从公开的 Pushary 仓库发布，以便 GitHub OIDC 能够证明对 io.github.Pushary/pushary 命名空间的所有权。发布后，请验证工作流和注册表结果。

手动备用流程，在此目录中运行：

curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
./mcp-publisher login github
./mcp-publisher publish

检查注册表实际提供的内容，这才是唯一重要的版本号：

curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=pushary"

该端点会返回所有版本，按从旧到新的顺序排列。读取 _meta."io.modelcontextprotocol.registry/official".isLatest 为 true 的条目；列表中的第一行是最旧的记录，而不是当前生效的记录。

贡献

欢迎贡献！提交拉取请求前，请阅读贡献指南。

安全

如果你发现安全漏洞，请负责任地报告。详情请参阅 SECURITY.md。

资助

本项目完全由爱沙尼亚软件开发机构 RalphNex OU 资助。

许可证

MIT - 版权所有 (c) 2025 RalphNex OU