# 开源发布流程

本项目是社区扩展，采用 [Pi 官方包格式](https://pi.dev/docs/latest/packages)。符合格式不代表官方维护或已经在包目录展示。兼容验证基线为 Pi 0.84.0。

## 发布结构

package.json.pi.extensions 指向 extension/index.ts，pi-package 关键字用于发现。Pi 核心库与 typebox 使用 peerDependencies: "*"；开发依赖实际版本由根锁文件固定。

归档包含 extension、shared、web/dist、README、MIT LICENSE 和维护文档。Monaco、worker、Markdown/KaTeX 资源本地打包，安装者不需要前端源码或构建工具。

prepack 保证普通 npm pack 在打包前构建。支持 npm 包与已构建本地源码；不提供直接 Pi Git 安装支持，因为 Pi 0.84.0 默认运行 npm install --omit=dev。

## 发布准备

在干净检出中运行：

```sh
npm ci
npm run release:prepare
```

release:prepare 依次执行：

1. Extension/Web 类型检查与日常测试。
2. Web 构建和真实 tarball 验收：离线安装、Pi 入口、五个工具与五个命令、首页、JavaScript 和 Monaco worker。
3. 真实 Pi RPC smoke，不调用模型。
4. 使用已验证产物生成根目录 pi-learning-agent-<version>.tgz，最后一步不再构建。

日常开发可分别运行 npm run check、npm run check:package 与 npm run smoke。Windows/Linux、Node.js 22/24 的 CI 配置位于 .github/workflows/ci.yml；本机运行不代表远程矩阵已经执行。

真实模型 E2E 见 CONTRIBUTING.md；历史报告不能代替当前版本验收。

## 发布

维护者核对 npm 包名所有权、版本、仓库地址和全部结果后，发布生成的那个文件：

```sh
npm publish ./pi-learning-agent-<version>.tgz --access public
```

将 <version> 替换为实际版本。此步骤需要发布者 npm 权限，准备脚本不会执行它。发布后在干净 Pi 环境验证：

```sh
pi install npm:pi-learning-agent@<version>
```

再验证学习启动、作答、停止与分支恢复，并实际检查包目录是否展示该版本。

## 撤回

发布前可删除归档并撤回代码。发布后采用新的修补版本修正；用户可显式安装此前可用版本。不要覆盖已发布版本或未经影响评估执行 npm unpublish。