Asigers/pi-knock
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.
可以做什么
- 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
English | 简体中文
离开终端。Pi 需要你的时候会来找你。
pi-knock 是一个 Pi coding agent 扩展,会在任务完成、失败或需要你输入时发送远程通知。可以通过 Pushover 推送到 iPhone / Apple Watch,通过 ntfy 使用托管或自建推送,也可以通过 Webhook 接入自己的自动化服务。
为什么需要 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,防止重复通知。