# 参与贡献

本项目是使用 Pi 官方包格式分发的 MIT 社区扩展。开发基线为 Pi 0.84.0、Node.js >=22.19.0 与 npm >=11。

## 开发与验证

根 `package-lock.json` 管理整个 npm workspace。不要在 `web/` 新建第二份锁文件。

```sh
npm ci
npm run check
npm run build:web
npm run pi
```

在 Pi 中运行 `/learn rust trait bounds`。完整交互需要扩展提供的本地 HTTP/SSE 与会话 token。

`npm run check` 包含两端类型检查以及日常测试，不构建发布包。改动安装、协议、目录或静态资源后运行 `npm run check:package` 和 `npm run smoke`；发布前统一运行 `npm run check:release`。

归档验收会真实打包、在系统临时目录离线安装，再用 Pi 加载包内入口并检查工作台和 Monaco worker；使用独立测试目录，不读取个人 Pi 上下文。

真实模型测试通过 `npm run e2e -- a --timeout 540` 与 `npm run e2e:browser` 单独运行。它们使用 Pi 配置的提供商和凭据，会消耗模型额度；浏览器测试要求 Microsoft Edge。普通持续集成不运行模型 E2E。

`npm run test:workspace` 使用真实 Microsoft Edge 和临时 loopback Vite 服务，通过虚构 API 验证 Monaco 编辑行为，不启动 Pi 或调用模型。修改代码编辑、只读范围或草稿恢复时运行它；配置独立于模型 E2E，目前不加入缺少 Edge 的日常 CI。

## 修改约定

保留结构化 tool result、顺序作答、跳过与取消的区别，以及按当前 Pi 分支恢复状态的语义。涉及协议与发布目录时同时检查 shared、package.json.files 和归档验收。

新增行为通过公开入口测试，避免替换内部 Broker/状态对象或依赖私有函数。按一个行为一次的红—绿—重构循环推进；修复确认的失败后再扩大检查范围。

每次落盘修改在 work.md 记录时间、问题、解决方式、变更文件、验证结果与撤回方式。提交 pull request 时说明具体场景、最终行为、检查结果和剩余限制。

不要提交会话 token、模型凭据、个人学习内容、node_modules、web/dist 或本地 .tgz。敏感问题的处理方式见 [SECURITY.md](SECURITY.md)。