@jetcrab/pi-desk-remote-debug

Pi Desk single-entry remote debugging gateway and tunnel UI

Packages

Package details

skill

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。