Skip to content
项目

Asigers/pi-knock has 115 GitHub stars and 9 forks. GitHot measured +1 stars in 24 hours, +1 in 7 days, and +1 in 15 days. Last checked 2026-11-15 15:55 UTC. Last push 2026-11-09.

这些数字如何统计

115 星标9 复刻 +1 24小时

可以做什么

  • Actually waits for completion — completion alerts are sent at agent_settled, after Pi has finished automatic retries and queued work.
  • Works away from your desk — notifications can reach your phone or watch instead of only the local terminal.
  • Reliable delivery — transient failures are retried automatically.
  • Lock-screen safe by default — prompt text is hidden unless you opt in.

实测星标增长

24小时
+1
7天
+1
15天
+1
1个月
更新延迟

各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。

关于

Remote notifications for the Pi coding agent — Pushover, ntfy, and webhooks when tasks finish or need your input.

开发工具

docs/README.zh-CN.md

原文

pi-knock

npm 版本 CI Pi 0.87+ MIT 许可证

English | 简体中文

离开终端。Pi 需要你的时候会来找你。

pi-knock 是一个 Pi coding agent 扩展,会在任务完成、失败或需要你输入时发送远程通知。可以通过 Pushover 推送到 iPhone / Apple Watch,通过 ntfy 使用托管或自建推送,也可以通过 Webhook 接入自己的自动化服务。

pi-knock 宣传演示:让 Pi 继续工作,在需要你时接收远程通知

pi-knock 手机通知示例

为什么需要 pi-knock?

桌面通知只有人在电脑旁时才有用。pi-knock 让你把任务交给 Pi 后真正离开终端:当任务完成,或 Pi 需要你输入和确认时,通知会直接到达手机或手表。

  • Pi 真正结束后再提醒 — 自动重试和排队任务都处理完、进入 settled 状态后才发送完成通知。
  • 只在需要你时回来 — Pi 等待输入或确认时主动通知你,不必反复查看终端。
  • 离开电脑也能收到 — 可通过 Pushover、ntfy 或自己的 Webhook 自动化接收提醒。

目录

功能特点

  • 真正完成后再提醒 — 使用 agent_settled,Pi 的自动重试和排队任务都结束后才发送完成通知。
  • 人可以离开电脑 — 通知发到手机或手表,而不是只在当前终端弹一下。
  • 投递更可靠 — 瞬时网络错误会自动重试。
  • 默认保护锁屏隐私 — 默认不把原始 Prompt 放进通知正文,需要时可主动开启。
  • 识别 Session — 如果给 Pi Session 设置了名称,会显示在通知标题里。
  • 不需要自建推送服务 — pi-knock 直接调用你配置的通知渠道。

快速开始

环境要求: Pi 0.87+、Node.js 22.19+。

1. 安装

推荐从 npm 安装:

pi install npm:@asigers/pi-knock

请只选择一种安装来源。不要同时安装 npm 版和 Git 版,否则 Pi 可能会加载两份扩展并发送重复通知。

如果需要测试未发布源码,可以使用带版本标签的 Git 版:

pi install git:github.com/Asigers/[email protected]

不确定是否重复安装时,运行 pi list,只保留一个 pi-knock 条目。

2. 配置

重启 Pi 或执行 /reload,然后启动配置向导:

/knock setup

选择通知渠道并填写配置。保存渠道配置后,会立即发送测试通知。

凭据隐私: Pi 的标准输入框不会隐藏输入内容。请只在私有终端或私有会话中填写凭据。

3. 验证

需要检查通知是否正常时,发送一条测试通知:

/knock test

如果没有收到通知,运行 /knock doctor 查看渠道配置和最近一次投递结果。

命令

在 Pi 内运行以下命令:

命令 作用
/knock setup 配置通知渠道和通知偏好
/knock status 查看当前配置
/knock test 发送实时测试通知
/knock doctor 查看渠道和最近一次投递诊断

通知渠道

渠道 适合场景
Pushover iPhone / Apple Watch
ntfy 托管或自建推送
Webhook 自己的服务和自动化流程

需要配置渠道时,可以查看 英文渠道配置指南 或 Pushover 完整配置指南。

通知规则

默认行为:

事件 是否通知
对话完成 是
等待输入 / 确认 是
对话失败 是
对话中止 否

通知标题会包含项目名;如果当前 Pi Session 设置了名称,也会一起显示。

为了避免敏感 Prompt 出现在手机或手表锁屏上,默认使用 project-only 模式,不发送原始 Prompt。需要显示 Prompt 时,执行 /knock setup,选择 Notification preferences 修改。

对于请求超时、瞬时网络错误以及 HTTP 429 / 5xx 等可重试错误,pi-knock 最多尝试 3 次(首次发送 + 2 次重试);永久性的 4xx 错误不会无意义重试。

Pushover 单次请求最多等待 10 秒,两次重试前默认等待 5 秒和 10 秒。ntfy 和 Webhook 保持单次 5 秒超时,重试前默认等待 1 秒和 3 秒。实际等待会加入少量随机抖动,并会遵守服务端返回的 Retry-After(最多 60 秒)。

投递失败保持静默:自动通知、/knock test 和配置向导中的测试都不会弹出失败警告或打印错误,测试反馈只显示成功的渠道。生命周期通知会在后台投递,不会因为重试阻塞 Pi 的 settled 边界。需要排查时,主动运行 /knock doctor 查看失败原因和尝试次数。最近一次报告会保存在本地,不包含通知正文或凭据。

请求超时不代表服务端没有接收到消息,因此重试偶尔可能产生重复通知。

配置

配置文件

配置向导默认写入以下两个文件:

~/.pi/agent/pi-knock/
├── config.json
├── credentials.json
└── last-delivery.json
  • config.json:保存通知偏好和不含密钥的渠道设置。
  • credentials.json:单独保存渠道密钥和令牌,请勿提交到仓库或分享文件内容。
  • last-delivery.json:保存最近一次脱敏后的投递状态和尝试次数,供 /knock doctor 查看。

可以通过 PI_KNOCK_HOME 修改默认目录,也可以通过 PI_KNOCK_CONFIG 和 PI_KNOCK_CREDENTIALS 分别指定文件路径。

配置示例

启用 Pushover 的最小 config.json 示例(凭据需单独配置):

{
  "projectName": "",
  "openUrl": "",
  "contentMode": "project-only",
  "notify": {
    "completed": true,
    "error": true,
    "aborted": false,
    "input": true
  },
  "pushover": {
    "enabled": true
  }
}

完整配置见 pi-knock.example.json 和 config.schema.json。

环境变量

环境变量会覆盖配置文件中的对应设置,适合 Pi-Web、容器、CI 和外部密钥管理工具。常用变量如下:

用途 变量
Pushover 凭据 PI_KNOCK_PUSHOVER_USER_KEY、PI_KNOCK_PUSHOVER_APP_TOKEN
ntfy 连接 PI_KNOCK_NTFY_SERVER、PI_KNOCK_NTFY_TOPIC、PI_KNOCK_NTFY_ACCESS_TOKEN
Webhook 连接 PI_KNOCK_WEBHOOK_URL、PI_KNOCK_WEBHOOK_BEARER
投递报告路径 PI_KNOCK_DELIVERY_REPORT(可选)
通知内容 PI_KNOCK_CONTENT_MODE(project-only 或 prompt)

更新与卸载

更新已安装的扩展:

pi update --extensions

卸载通过 npm 安装的版本:

pi remove npm:@asigers/pi-knock

如果通过 GitHub 安装,请改用 pi remove git:github.com/Asigers/pi-knock。

开发

npm ci --ignore-scripts
npm run check
npm pack --dry-run
pi -ne -e ./src/index.ts

本地测试时使用 -ne,可以避免同时加载已经安装的 pi-knock,防止重复通知。

相关文档

许可证

MIT