@jetcrab/pi-desk-remote-debug
Pi Desk single-entry remote debugging gateway and tunnel UI
Package details
Install @jetcrab/pi-desk-remote-debug from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@jetcrab/pi-desk-remote-debug- Package
@jetcrab/pi-desk-remote-debug- Version
1.1.25- Published
- Nov 16, 2026
- Downloads
- 3,043/mo · 919/wk
- Author
- jetcrab
- License
- Apache-2.0
- Types
- skill
- Size
- 530.6 KB
- Dependencies
- 3 dependencies · 0 peers
Pi manifest JSON
{
"skills": [
"./skills"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
Pi Desk — pi-desk-remote-debug
包名:@jetcrab/pi-desk-remote-debug。插件接口以源码导出为准,个人配置不随包分发。
官方说明:使用说明
公网调试需要由同机 Pi Desk 桌面端托管服务,并在桌面“隧道 → 连接设置”中保存控制服务地址和密钥。插件不附带或自动下载独立隧道程序;未由桌面端托管时,公网调试不可用。
本地入口就绪后即可访问,端口登记、Gateway 和公网隧道在后台准备。公网端口被占用、未由桌面端托管、隧道连接失败或运行后退出,均不停止本地项目;错误可在运行详情与日志查看。本地项目只在显式停止、插件关闭或项目命令退出时结束。
插件调用同机桌面程序的 --tunnel-client --stats,每次调试使用独立临时提供端身份,不复用桌面提供端私钥,也不修改桌面发布表。项目配置位于 .pi/pi-desk.yaml 的 plugins.remote-debug;公网访问仍由普通浏览器或 TCP 程序直接访问 host:port,不要求访问者安装隧道客户端。
项目配置示例(写入时保留共享文件其他分组):
plugins:
remote-debug:
version: 1
profiles:
web:
command: pnpm dev
entryPort: 43000
publicPort: 11001
routes:
/api: 43001
全局配置为 <AgentDir>/config/pi-desk.yaml 的同名分组,localRange、publicRange 与服务字段可以共存。项目按业务 CWD 精确读取,不搜索父目录;只有当前项目原始分组存在时才识别为已配置,再按默认、全局、项目逐字段合并,对象递归覆盖、数组整体替换。旧 .pi/remote_debug.yaml 不读取或迁移。
CLI 的项目保存只处理显式提交的项目启动项,不把全局服务或默认值复制到项目。save 整体替换项目启动项,保留该层范围等其他字段;ranges 只保存全局范围,保留同组全局服务。登记独立保存在 <AgentDir>/pi-desk/remote-debug-registrations.json,项目读取与登记同步不回写默认范围。
使用支持客户端映射的桌面和宿主时,在另一台电脑的桌面工作台打开远程调试,运行就绪后会自动建立本地映射;“本地”行显示当前电脑的回环地址及实际“直连/中继”标签。映射经过调试 Gateway,保留 HTTP/WebSocket 路由;连接失败不影响下面的公网地址。两端需使用相同隧道控制服务并配置有效密钥。localhost/回环工作台不创建映射;普通浏览器及旧宿主保持原访问方式。关闭调试弹窗保留连接,停止调试、释放页面或退出客户端时清理。
日志中的“活动 TCP”是当前业务转发流数量,不是请求数或人数;公网入口的 direct/relay 仅表示网关到提供端的实际内层路径。连接统计只属于当前调试 CLI,不并入桌面本进程统计。
使用该插件前,桌面端须支持 --stats,并与隧道服务端同步使用 v2 协议;不支持时会提示升级,不静默移除统计参数或降级到旧 Noise 协议。升级在维护窗口进行,活动 TCP 会断开;回退使用备份的旧制品与配置。部署及 CLI 合同见隧道手册。
启动或重启时,若本机端口已被占用,会列出端口、进程名和 PID,询问是否强制结束并继续启动;取消不影响原服务。确认后重新核对占用者,变化时需再次确认。无法识别占用者、系统或 Pi Desk 自身占用时不提供强杀;其他活动调试任务占用的本机端口仍需手动处理。macOS/Linux 的进程查询需要系统提供 lsof。
许可与来源见本目录的 LICENSE 和 SOURCE.md。