@huntye1/pi-remote-tools

English

这是一个 Pi package，它为多个命名远程工作区提供基于 SSH 的附加工具，同时保留 Pi 原有的本地工具。

扩展注册四个工具：

• remote_read
• remote_write
• remote_edit
• remote_bash

每次远程工具调用都必须提供 workspace。扩展不设置默认远程工作区；Pi 会区分本地工作区和每个已配置的远程工作区，意图不明确时应先询问。

本地 read、write、edit、bash，以及用户输入的 ! 命令仍然在本机执行。

安装

安装到当前 Pi 用户：

pi install npm:@huntye1/pi-remote-tools

或者只添加到当前受信任项目：

pi install --local npm:@huntye1/pi-remote-tools

扩展调用系统 ssh 命令。认证、Host alias、ProxyJump 等传输配置应放在 ~/.ssh/config 中，并且认证必须可非交互完成。

配置项目

创建 <project>/.pi/remote-tools.json：

{
  "local": {
    "desc": "本地集成与工具仓库"
  },
  "workspaces": {
    "frontend": {
      "desc": "前端应用与浏览器测试",
      "target": "frontend-box",
      "cwd": "/srv/frontend"
    },
    "backend": {
      "desc": "后端 API、数据模型与服务测试",
      "target": "backend-box",
      "cwd": "/srv/backend",
      "path": "/home/user/.local/bin:/usr/local/bin:/usr/bin:/bin"
    }
  }
}

local.desc 和每个远程工作区的 desc 都是必填项。它们用于告诉 agent 各工作区的职责，避免将某个工作区视为默认目标。

每个远程工作区需要：

• 符合 [A-Za-z][A-Za-z0-9_-]* 的唯一别名
• desc
• target

cwd 可选；省略时，首次使用会通过远端 pwd -P 获取。path 可选；省略时，扩展会在首次使用时探测远端登录 shell，以保留 nvm、fnm 等工具加入的 PATH。

local 是保留的远程工作区别名。只有 Pi 信任项目后才会读取项目配置。

破坏性变更： 已不再支持旧版单工作区顶层 target、cwd、path，也不支持 --remote-ssh、--remote-cwd、--remote-path 参数。

工具调用

每次调用必须明确指定远程工作区：

{
  "workspace": "frontend",
  "path": "src/app.ts"
}

{
  "workspace": "backend",
  "command": "npm test",
  "timeout": 300
}

远程工具会拒绝 workspace: "local"；本地操作应使用 Pi 自带的本地工具。

工作区指令

扩展不会在启动时读取每台主机上的指令文件。它会提示 agent 先选择相关工作区，再按需读取适用的 AGENTS.md：

• 本地 AGENTS.md 使用本地工具读取
• 远程 AGENTS.md 使用带明确 workspace 的 remote_read 或 remote_bash
• 检查工作区根目录到目标目录之间的嵌套 AGENTS.md
• 不连接无关工作区，也不把其指令注入上下文

这样可以避免启动 SSH 流量、过期指令缓存、无关提示词增长和跨工作区指令冲突。

状态

在交互式 Pi 会话中执行 /remote-tools-status，可以查看本地工作区和所有远程工作区的路径与说明。

说明

• 相对远程路径基于已配置或自动发现的 cwd 解析。
• 本地项目根目录内的绝对路径会转换为远程 cwd 下对应路径；其他绝对路径按远程绝对路径处理。
• 每个工作区的 cwd 和 PATH 都独立延迟发现并缓存；单个连接失败不会禁用其他工作区。
• 远程文件操作会以 remote:<workspace>:<path> 的形式进入 Pi compaction 文件摘要。
• 用户输入的 ! 和 !! 命令仍在本地执行。

开发与发布

Pi 会通过扩展加载器直接运行 package 中的 TypeScript，因此不需要编译 JavaScript。

npm run check
npm run pack:check
pi --extension ./packages/pi-remote-tools
npm publish --access public

Pi 宿主 API 作为 optional peer dependencies 由 Pi 提供。发布包包含扩展源码、中英文 README、LICENSE 和 package 元数据。

许可证

MIT