---
name: rpi-extension-packaging
description: >
  Use when a repository should become installable by rpi (an "rpi extension") and appear in the
  rpi market catalog. Converts an existing tool/repo into the manifest + release layout the
  catalog parser expects, adds CI (fmt / test / clippy / host smoke test / release), then produces
  the topic + manifest checklist.
license: MIT
metadata:
  target: rpi-extension
  schema: v1
  reference_repo: https://github.com/pi-rust/rpi-extension
---

# 把仓库变成可被 rpi 收录的扩展

目标：`rpi install <name> --github <owner>/<repo>` 能装上，CI 能证明它一直能装上，目录发现任务能自动收录。

官方参考仓库：**pi-rust/rpi-extension**。它的 `.github/workflows/` 就是"每个扩展一份 checks + 一份 release"的样板，直接抄再改名，不要从零写。

## 0. 判定形态

| 形态 | 条件 | 收录方式 |
|---|---|---|
| Rust cdylib 扩展 | `Cargo.toml` 的 `[lib] crate-type` 含 `cdylib` | 源码构建（`build=source`） |
| 预编译扩展 | Release 里按平台放动态库 + `rpi-extension.json` | 预编译（`build=prebuilt`，推荐） |
| 集合包（package） | 多个扩展/skill 打包 | **本期不解析**，不要按扩展处理 |

## 1. 仓库根目录放清单

`rpi-extension.json`：

```json
{
  "schemaVersion": 1,
  "name": "rpi-your-extension",
  "version": "0.1.0",
  "type": "extension",
  "description": "一句话说明这个扩展做什么",
  "license": "MIT",
  "targets": [
    { "target": "x86_64-unknown-linux-musl" },
    { "target": "aarch64-unknown-linux-musl" },
    { "target": "x86_64-apple-darwin" },
    { "target": "aarch64-apple-darwin" },
    { "target": "x86_64-pc-windows-msvc" }
  ],
  "install": "rpi install rpi-your-extension --github owner/repo"
}
```

规则：

- `name` 小写字母/数字/`-`/`_`/`.`，与 crate 名一致
- `type` 必须是 `extension`；未知值会被归为 `other`（不会免审）
- `install` 写**完整**命令，不要只写 `rpi install name`
- 不要在 `install` 里同时用 `--path` 和 `--github`

## 2. 打 Release

tag 命名（解析器按前缀归属下载量）：

```text
<name>-v<version>      例：rpi-web-v0.1.66
```

每个 target 一个资产，外加 `rpi-extension.json`。

## 3. 打 topic

仓库 Topics 添加 `rpi-extension`：命中且有清单 → 免审上架并带「官方」标记；缺清单 → 进待审核。

## 4. 平台前提（macOS / Linux / Windows 都要能跑）

| | macOS（Apple Silicon） | Linux | Windows |
|---|---|---|---|
| 工具链 | `rustup`（stable） | `rustup` | `rustup`（MSVC target） |
| 原生 target | `aarch64-apple-darwin` | `x86_64-unknown-linux-musl` | `x86_64-pc-windows-msvc` |
| 交叉到 Linux musl | **需要 zig**：`brew install zig && cargo install cargo-zigbuild`，然后 `cargo zigbuild --release --target x86_64-unknown-linux-musl` | 装 `musl-tools pkg-config` 即可 | 不常用 |
| 产物路径 | `target/release/librpi_x.dylib` | `target/release/librpi_x.so` | `target/release/rpi_x.dll` |
| 装宿主 | `curl -fsSL .../install.sh \| sh` | 同左 | PowerShell：`irm .../install.ps1 \| iex` |

注意：macOS 上默认 `cargo build --target x86_64-unknown-linux-musl` 会失败（缺 `x86_64-linux-musl-gcc`），这正是要用 `cargo zigbuild` 的原因。CI 里不要试图在 macOS runner 上产出 Linux 产物，用 `ubuntu-latest` 或容器。

## 5. CI（必须，不要只在本机跑过）

官方仓库的做法是**每个扩展一个 checks 工作流 + 一组发布工作流**，从 `.github/workflows/` 复制对应文件改名即可：

| 参考文件 | 用途 | 怎么改 |
|---|---|---|
| `office-checks.yml` | 单包三平台 fmt/test/clippy | 把 `rpi-office` 换成你的 crate 名 |
| `server-checks.yml` | 带 `paths` 过滤、`RUSTFLAGS=-D warnings` | 同上，路径改成你的包目录 |
| `musl-checks.yml` | 容器里编 musl 并真正加载插件 | 换成你的构建脚本 |
| `release-cargo.yml` | 版本递增 + crates.io 发布 | 跟本仓库的发布节奏对齐 |
| `release-assets.yml` | 各平台产物 + `rpi-extension.json` 资产 | 换成你的 target 矩阵 |

### 5.1 基础检查（三平台）

```yaml
name: <name> checks

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  checks:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    timeout-minutes: 30
    env:
      CARGO_INCREMENTAL: '0'
      CARGO_PROFILE_DEV_DEBUG: '0'
      CARGO_PROFILE_TEST_DEBUG: '0'
      RUSTFLAGS: '-D warnings'
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt, clippy
      - uses: Swatinem/rust-cache@v2
      - name: Format
        run: cargo fmt --check -p <name>
      - name: Test
        run: cargo test --locked -p <name>
      - name: Clippy
        run: cargo clippy --locked -p <name> --all-targets --no-deps -- -D warnings
```

要点：

- `RUSTFLAGS: -D warnings` —— 警告即失败
- `persist-credentials: false` —— PR 不需要写权限
- `fail-fast: false` —— 一个平台挂了仍要看到其他平台
- `--no-deps` —— 只对自己的 crate 做 clippy
- 依赖系统库时按平台装：Ubuntu `apt-get install libasound2-dev`、macOS 一般自带、Windows 用 `vcpkg`/`choco`

### 5.2 宿主冒烟：**必须测 PR 的代码**

⚠️ 常见错误：在 PR 里跑 `rpi install <name> --github <repo>`。这装的是**默认分支或已发布 Release**，不是这个 PR 的 commit，等于什么都没测。

正确做法是本地构建 cdylib，再用 `--extensions-dir` 让宿主加载：

```yaml
  host-smoke:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]      # Windows 见下方注释
    runs-on: ${{ matrix.os }}
    timeout-minutes: 30
    permissions:
      contents: read                            # 不注入任何 secret
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - name: Build cdylib (PR code)
        run: cargo build --release --locked -p <name>
      - name: Install rpi host (unix)
        if: runner.os != 'Windows'
        run: curl -fsSL https://raw.githubusercontent.com/bigfish1913/pi-rust/main/scripts/install.sh | sh
      - name: Install rpi host (windows)
        if: runner.os == 'Windows'
        shell: pwsh
        run: irm https://raw.githubusercontent.com/bigfish1913/pi-rust/main/scripts/install.ps1 | iex
      - name: Load the freshly built extension
        run: rpi --extensions-dir target/release --no-session -p 'echo ok'
```

说明：

- 产物目录就是 `target/release`，macOS 是 `librpi_x.dylib`、Linux 是 `.so`、Windows 是 `.dll`，`--extensions-dir` 会按平台找对应后缀
- 宿主二进制下载地址与仓库一致即可；没有预编译时改用 `cargo install rpi-cli --locked`
- **不要给 secrets、不要给写权限、必须设 timeout**；只在 `pull_request` / `workflow_dispatch` 触发，不要用 `pull_request_target`
- 扩展注册了工具时，再断言一次确实注册成功（例如跑一个最小工具调用）

发布后的另一次冒烟（可选，验证 Release 真能装）：

```bash
rpi install <name> --github <owner>/<repo> --force
rpi --no-session -p 'echo ok'
```

### 5.3 发布工作流

```yaml
on:
  push:
    tags: ['*-v*']

permissions:
  contents: write

concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false

jobs:
  build:
    strategy:
      matrix:
        include:
          - target: x86_64-unknown-linux-musl
            os: ubuntu-latest
          - target: aarch64-unknown-linux-musl
            os: ubuntu-24.04-arm        # 或 cross/zigbuild
          - target: x86_64-apple-darwin
            os: macos-13                # Intel；在 macos-latest(arm64) 上交叉也可以
          - target: aarch64-apple-darwin
            os: macos-latest
          - target: x86_64-pc-windows-msvc
            os: windows-latest
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
        with:
          targets: ${{ matrix.target }}
      - run: cargo build --release --locked --target ${{ matrix.target }}
      # 打包：unix 用 tar.gz、Windows 用 zip，文件名带 <version> 与 <target>，
      # 并把 rpi-extension.json 一起作为资产；manifest 的 targets 必须与这里一一对应
```

发布检查（对应 `release-assets.yml` / `release-checks.yml`）：

- 资产名带 `<version>` 与 `<target>`，和 manifest 的 `targets` 一致
- `rpi-extension.json` 与资产同版本
- 声明了哈希就计算 SHA-256 写进 manifest
- 打 tag 前先跑 checks，绿色才发

## 6. 自检清单（三个平台）

### macOS / Linux

```bash
cargo fmt --check -p <name>
cargo test --locked -p <name>
cargo clippy --locked -p <name> --all-targets --no-deps -- -D warnings

# 加载刚编出来的产物（macOS 是 .dylib，Linux 是 .so）
cargo build --release -p <name>
rpi --extensions-dir target/release --no-session -p 'echo ok'

# 清单可达（走 contents API，raw.githubusercontent 在部分网络下不通）
curl -s "https://api.github.com/repos/OWNER/REPO/contents/rpi-extension.json?ref=main" \
  -H 'Accept: application/vnd.github.raw' | head

# Release 资产
gh release view <name>-v<version> --json assets --jq '.assets[].name'

# 真装一次（发布后）
rpi install <name> --github OWNER/REPO --force
rpi --no-session -p 'echo ok'
```

### Windows（PowerShell）

```powershell
cargo fmt --check -p <name>
cargo test --locked -p <name>
cargo clippy --locked -p <name> --all-targets --no-deps -- -D warnings

cargo build --release -p <name>
rpi --extensions-dir target/release --no-session -p 'echo ok'   # 加载 target/release/<name>.dll

irm https://api.github.com/repos/OWNER/REPO/contents/rpi-extension.json?ref=main `
  -Headers @{ Accept = 'application/vnd.github.raw' } | Select-Object -First 5

rpi install <name> --github OWNER/REPO --force
```

跨平台注意：`sed -i`、`tar -xzf`、`chmod` 在 Windows 上不可用；脚本要么写成跨平台，要么在 CI 里用 `shell: bash`。

## 7. 常见失败

| 现象 | 原因 |
|---|---|
| 收录后安装命令为空 | 根目录没有 `rpi-extension.json`，也没有 cdylib |
| 进待审核而不是直接上架 | topic 不是 `rpi-extension`，或 `type` 不是 `extension` |
| 版本显示为 `—` | 清单里没有 `version` |
| 下载量一直是 0 | Release tag 不是 `<name>-v<version>` 形式 |
| 只在 macOS 绿、Linux CI 红 | 少了 musl/aarch64 目标，或缺 `musl-tools`/`pkg-config` |
| 本机能加载、宿主 CI 失败 | 宿主版本过旧或扩展 ABI 不匹配；在 CI 里显式装最新宿主 |
| 同名包被占用 | 与已上架包冲突，换名或联系维护者合并 |

## 8. 交付物

1. 根目录 `rpi-extension.json`
2. `rpi-extension` topic
3. 一个匹配的 Release（预编译形态）
4. `.github/workflows/<name>-checks.yml`（fmt/test/clippy，三平台）
5. 一个宿主冒烟 job（装宿主 + 真装扩展 + 启动）
6. 发布工作流（tag 触发，产物 + manifest）
7. README 说明：权限、网络访问、持久化文件、卸载方式
