# @huntye1/pi-remote-tools

[English](README.md)

这是一个 [Pi](https://pi.dev/) package，它为多个命名远程工作区提供基于 SSH 的附加工具，同时保留 Pi 原有的本地工具。

扩展注册四个工具：

- `remote_read`
- `remote_write`
- `remote_edit`
- `remote_bash`

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

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

## 安装

安装到当前 Pi 用户：

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

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

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

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

## 配置项目

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

```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` 参数。

## 工具调用

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

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

```json
{
  "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。

```bash
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