# Releasing pi-research-loop

公共源码仓库：<https://github.com/kuan-er/pi-research-loop>。

## 1. 检查公共 Git 仓库

```bash
git remote -v
git push origin main
```

仓库元数据应指向同一个公共地址：

```bash
npm pkg get repository homepage bugs
```

建议使用 `v0.1.0` 这样的 tag 作为可复现安装版本。

## 2. 发布前检查

```bash
npm ci
npm run release:check
npm pack --dry-run
npm audit --omit=dev --audit-level=high
```

检查 tarball 中至少包含：

```text
dist/
templates/
skills/
prompts/
README.md
CHANGELOG.md
package.json
```

检查 package 元数据：

```bash
npm pkg get name version license bin pi publishConfig
```

## 3. 发布到 npm

需要 npm 账号对 package 名称 `pi-research-loop` 有发布权限。

```bash
npm login
npm whoami
npm publish --access public
```

发布后验证：

```bash
npm view pi-research-loop version dist.tarball
npm install --global pi-research-loop@0.1.0
pi install npm:pi-research-loop@0.1.0
```

如果名称已被占用，需要先改 package 名称，例如改成组织 scope：

```json
{
  "name": "@your-org/pi-research-loop"
}
```

对应安装命令为：

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

## 4. 创建 Git tag

npm 发布成功后再创建 tag：

```bash
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0
```

Git 安装用户可以固定这个 tag：

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

## 5. 后续版本

修改 `package.json` 版本并更新 `CHANGELOG.md`：

```bash
npm version patch   # 0.1.0 -> 0.1.1
npm run release:check
npm publish --access public
git push origin main --follow-tags
```

对于破坏性 API 修改使用：

```bash
npm version major
```

## 6. CI/CD

`.github/workflows/ci.yml` 会在 push 和 Pull Request 时运行 build/test。

如需 GitHub Release 自动发布 npm，可以增加 workflow，并配置仓库 secret：

```text
NPM_TOKEN=<npm automation token>
```

自动发布 workflow 必须使用：

```yaml
env:
  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

不要把 npm token 写入仓库、README、Git history 或 `.env`。

## 7. 发布后的用户说明

对外发布时至少告诉用户：

1. Node.js、Git、Pi 的最低版本；
2. `npm install --global` 和 `pi install` 是两个独立步骤；
3. `prl init` 必须在研究 Git 仓库中执行；
4. Task worktree 与主工作区的区别；
5. Run 事件不会让 LLM 定时轮询；
6. MLflow/W&B 是可选集成；
7. PRL 不自动 push、merge 或删除 worktree；
8. `.env`、密钥、模型权重和实验输出不会被自动 checkpoint。

完整中文文档见 [`INSTALL.zh-CN.md`](./INSTALL.zh-CN.md)。