# pi-research-loop 安装与使用

本文面向需要在多台服务器部署 PRL 的用户。

## 先决条件

每台服务器独立安装以下软件：

- Node.js >= 22
- Git >= 2.20（需要 `git worktree`）
- Pi >= 0.82.1
- Python、CUDA、MLflow、W&B 等实验依赖由研究项目自己管理

检查环境：

```bash
node --version
git --version
pi --version
```

PRL 不需要中央服务。每台机器有自己的研究仓库、`.pi-research/`、worktree、Run 记录和 pending event。

## 推荐安装方式：npm

发布到 npm 后，在每台服务器执行：

```bash
npm install --global pi-research-loop@0.4.0
pi install npm:pi-research-loop@0.4.0
```

这里有两个安装动作：

1. `npm install --global` 安装 `prl` 命令；
2. `pi install` 把 Extension、Skill 和 Prompt 注册到 Pi。

验证：

```bash
prl --help
pi list
```

升级到新版本：

```bash
npm install --global pi-research-loop@latest
pi update npm:pi-research-loop
```

生产环境建议固定版本，不使用 `latest`：

```bash
npm install --global pi-research-loop@0.1.0
pi install npm:pi-research-loop@0.1.0
```

## 从公共 Git 安装

适合 npm 尚未发布，或者需要固定某个 Git tag 的情况。当前公共仓库地址为：

```bash
export PRL_REPO=https://github.com/kuan-er/pi-research-loop.git
export PRL_VERSION=v0.4.0

npm install --global "git+${PRL_REPO}#${PRL_VERSION}"
pi install "${PRL_REPO}@${PRL_VERSION}"
```

如果仓库是 SSH：

```bash
npm install --global "git+ssh://git@github.com/kuan-er/pi-research-loop.git#v0.1.0"
pi install "git:git@github.com:kuan-er/pi-research-loop@v0.1.0"
```

Git 安装依赖目标服务器能访问仓库，并且有正确的 SSH key 或 HTTPS credential。

## 从本地目录安装

开发或内网部署可以使用：

```bash
npm install --global /opt/pi-research-loop
pi install /opt/pi-research-loop
```

源码目录中必须已经存在 `dist/`。如果是刚 checkout 的源码：

```bash
npm ci
npm run build
```

## 从 release tarball 安装

在构建机上：

```bash
npm ci
npm run release:check
npm pack
```

把生成的 `pi-research-loop-0.1.0.tgz` 复制到目标机器后：

```bash
npm install --global ./pi-research-loop-0.1.0.tgz
```

Pi Extension 仍需从解包后的 package 目录加载。最简单的内部部署方式是把 tarball 解压到固定路径：

```bash
mkdir -p /opt/pi-research-loop
tar -xzf pi-research-loop-0.1.0.tgz --strip-components=1 -C /opt/pi-research-loop
pi install /opt/pi-research-loop
```

## 初始化一个研究项目

```bash
cd /srv/my-research-project
prl init
prl doctor
```

初始化后应看到：

```text
AGENTS.md
research/PROJECT.md
research/STATE.yaml
research/DECISIONS.md
research/EXPERIMENTS.md
research/hypotheses/
.pi-research/config.yaml
runs/
```

## 一次完整实验

```bash
# 从研究仓库主工作区执行
prl task start --hypothesis H001 --name implementation-route

# 把返回的 worktree 路径交给 Pi Agent；同一假设和实现路线的后续阶段继续复用它
prl task checkpoint T-... --message "phase: geometry"

# 每次实验创建新的 Run；启动前会自动 checkpoint 当前代码
prl run launch --task T-... -- python train.py

prl run inspect R-...
prl run logs R-... --tail 100
prl experiments rebuild
prl task finish T-...
```

每个 Task 对应一条实现路线及其 branch/worktree，同一假设的后续阶段默认复用活动 Task。每个阶段可以用 `prl task checkpoint` 创建独立 commit，每次实验创建新的 Run，并在启动前自动 checkpoint。只有稳定 baseline、并发 agent 或可丢弃实验才应通过 `--new-worktree-reason` 创建第二个 worktree。PRL 不会自动 push、merge 或删除 worktree；路线完成后统一 review 并合并到 main。

### 依赖 Run 与 GPU handoff

如果后续实验必须在前一个 Run 完成后立即启动，不要等待 `wake_agent`。应在父 Run 完成前预先排队：

```bash
prl run launch --task T-... --gpu 6 -- python train_long.py
prl run enqueue --task T-... --depends-on R-... \
  --checkpoint-path /tmp/checkpoint.pt --gpu 6 --gpu-wait-seconds 86400 \
  -- python train_next.py
```

worker 会自动等待父 Run 成功、验证 checkpoint、获取 PRL GPU lease，并在 GPU 可用时启动后续 Run。lease 只能协调 PRL 管理的进程；如果需要防止外部作业抢占 GPU，应使用 Slurm 等真实调度器。

## Pi 中的推荐提示词

```text
调用 prl_context 读取当前研究状态和活动 Task。
同一假设、同一实现路线优先复用活动 Task/worktree；仅在没有兼容 Task 时调用 prl_task_start。
阶段结束时调用 prl_task_checkpoint；每次实验调用新的 prl_run_launch，并声明 CUDA OOM、超时和 checkpoint 文件事件。
不要轮询进程或日志；等待 [PRL EVENT] 通知。
收到事件后使用 prl_run_inspect 做有限长度检查，然后决定修改、retry 或停止。
```

## 事件配置

```yaml
events:
  - id: cuda_oom
    type: log.regex
    pattern: "CUDA out of memory"
    source: both
    max_matches: 1
    actions: [terminate, wake_agent]

  - id: checkpoint_ready
    type: file.created
    path: outputs/best.ckpt
    actions: [record]

  - id: timeout
    type: timer.timeout
    after_seconds: 28800
    actions: [terminate, wake_agent]
```

`process.exit` 总会自动添加。实验期间 Pi 可以退出，detached runner 会继续运行；事件会保存到 `.pi-research/pending/`，Pi 下次启动时投递。

## MLflow 和 W&B

编辑 `.pi-research/config.yaml`：

```yaml
tracking:
  mlflow:
    enabled: true
    tracking_uri_env: MLFLOW_TRACKING_URI
    experiment_name: my-project
    required: false
  wandb:
    enabled: true
    group: baseline
    tags: [research]
```

目标机器设置：

```bash
export MLFLOW_TRACKING_URI=https://mlflow.example.com
export WANDB_API_KEY=...
```

PRL 会注入以下变量：

```text
PRL_RUN_ID
PRL_TASK_ID
PRL_HYPOTHESIS_ID
PRL_GIT_COMMIT
WANDB_RUN_ID
WANDB_NAME
WANDB_GROUP
WANDB_TAGS
```

参考 `examples/wandb_minimal.py`。

## 多台服务器部署建议

每台服务器分别执行 npm/Pi 安装。研究仓库可以从 Git clone，但实验状态默认不共享：

- 每台机器有自己的 Run 目录；
- 每台机器有自己的 pending event；
- MLflow 可以作为跨机器的中央实验档案；
- W&B 可以作为实时曲线和系统指标平台；
- 不要把 `.env`、模型权重、密钥和 `runs/` 输出提交到 Git。

如果需要统一版本，固定 npm 版本或 Git tag，并在部署脚本中同时执行 `npm install --global` 和 `pi install`。