earendil-works--pi
wehub-resource-sync
106 行
5.9 KiB
Markdown
106 行
5.9 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/earendil-works/pi) · [上游 README](https://github.com/earendil-works/pi/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<p align="center">
|
||
<a href="https://pi.dev">
|
||
<img alt="pi logo" src="https://pi.dev/logo-auto.svg" width="128">
|
||
</a>
|
||
</p>
|
||
<p align="center">
|
||
<a href="https://discord.com/invite/3cU7Bz4UPx"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
|
||
<a href="https://www.npmjs.com/package/@earendil-works/pi-coding-agent"><img alt="npm" src="https://img.shields.io/npm/v/@earendil-works/pi-coding-agent?style=flat-square" /></a>
|
||
</p>
|
||
|
||
> 默认情况下，新贡献者提交的新 issue 和 PR 会自动关闭。维护者会每日审查被自动关闭的 issue。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
|
||
|
||
# Pi Agent Harness
|
||
|
||
这是 Pi agent harness 项目的主仓库，其中包含我们的可自扩展编码 agent。
|
||
|
||
* **[@earendil-works/pi-coding-agent](packages/coding-agent)**：交互式编码 agent CLI
|
||
* **[@earendil-works/pi-agent-core](packages/agent)**：支持工具调用与状态管理的 Agent 运行时
|
||
* **[@earendil-works/pi-ai](packages/ai)**：统一的多提供商 LLM API（OpenAI、Anthropic、Google 等）
|
||
|
||
了解更多关于 Pi 的信息：
|
||
|
||
* [访问 pi.dev](https://pi.dev), 项目官网，含演示 demo
|
||
* [阅读文档](https://pi.dev/docs/latest), 你也可以让 agent 自行讲解
|
||
|
||
## 所有软件包
|
||
|
||
| 软件包 | 说明 |
|
||
|---------|-------------|
|
||
| **[@earendil-works/pi-ai](packages/ai)** | 统一的多提供商 LLM API（OpenAI、Anthropic、Google 等） |
|
||
| **[@earendil-works/pi-agent-core](packages/agent)** | 支持工具调用与状态管理的 Agent 运行时 |
|
||
| **[@earendil-works/pi-coding-agent](packages/coding-agent)** | 交互式编码 agent CLI |
|
||
| **[@earendil-works/pi-tui](packages/tui)** | 支持差分渲染的终端 UI 库 |
|
||
|
||
有关 Slack/聊天自动化与工作流，请参阅 [earendil-works/pi-chat](https://github.com/earendil-works/pi-chat).
|
||
|
||
## 权限与容器化
|
||
|
||
Pi 不包含用于限制文件系统、进程、网络或凭证访问的内置权限系统。默认情况下，它以启动它的用户和进程的权限运行。
|
||
|
||
若需要更强的隔离边界，请对 Pi 进行容器化或沙箱化。有关三种模式，请参阅 [packages/coding-agent/docs/containerization.md](packages/coding-agent/docs/containerization.md)：
|
||
|
||
- **Gondolin extension**：将 `pi` 和提供商认证保留在宿主机上，同时将内置工具和 `!` 命令路由到本地 Linux 微型虚拟机中。
|
||
- **Plain Docker**：在本地容器中运行整个 `pi` 进程，以实现简单隔离。
|
||
- **OpenShell**：在策略控制的沙箱中运行整个 `pi` 进程。
|
||
|
||
## 贡献
|
||
|
||
贡献指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)，项目特定规则（适用于人类与 agent）请参阅 [AGENTS.md](AGENTS.md)。Pi 的更长期计划也可在 [RFCs](https://rfc.earendil.com/keyword/pi/).
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
npm install --ignore-scripts # Install all dependencies without running lifecycle scripts
|
||
npm run build # Build all packages
|
||
npm run check # Lint, format, and type check
|
||
./test.sh # Run tests (skips LLM-dependent tests without API keys)
|
||
./pi-test.sh # Run pi from sources (can be run from any directory)
|
||
```
|
||
|
||
## 供应链加固
|
||
|
||
我们将 npm 依赖变更视为经审查的代码变更。
|
||
|
||
- 直接外部依赖锁定为精确版本。内部 workspace 软件包仍使用版本范围。
|
||
- `.npmrc` 会设置 `save-exact=true` 和 `min-release-age=2`，以避免在 npm 解析期间遇到当日发布的依赖。
|
||
- `package-lock.json` 是依赖的唯一真实来源。pre-commit 会阻止意外提交 lockfile，除非设置了 `PI_ALLOW_LOCKFILE_CHANGE=1`。
|
||
- `npm run check` 会校验锁定的直接依赖、原生 TypeScript 导入兼容性以及生成的 coding-agent shrinkwrap。
|
||
- 发布的 CLI 软件包包含 `packages/coding-agent/npm-shrinkwrap.json`（由根 lockfile 生成），用于为 npm 用户锁定传递依赖。
|
||
- 发布冒烟测试使用 `npm run release:local`，在标记发布前于仓库外构建、打包并创建隔离的 npm 与 Bun 安装。
|
||
- 本地发布安装、文档中的 npm 安装以及 `pi update --self` 在支持的情况下使用 `--ignore-scripts`。
|
||
- CI 使用 `npm ci --ignore-scripts` 安装，定时 GitHub workflow 会运行 `npm audit --omit=dev` 以及 `npm audit signatures --omit=dev`。
|
||
- Shrinkwrap 生成对依赖 lifecycle 脚本设有显式允许列表；新的 lifecycle 脚本依赖在通过审查前会导致检查失败。
|
||
|
||
## 分享你的开源编码 agent 会话
|
||
|
||
如果你在开源工作中使用 Pi 或其他编码 agent，请分享你的会话。
|
||
|
||
公开的开源会话数据有助于用真实世界的任务、工具使用、失败与修复来改进编码 agent，而非仅依赖玩具基准测试。
|
||
|
||
完整说明请参阅 [X 上的这篇帖子](https://x.com/badlogicgames/status/2037811643774652911).
|
||
|
||
要发布会话，请使用 [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). 阅读其 README.md 了解设置说明。你只需要 Hugging Face 账户、Hugging Face CLI 以及 `pi-share-hf`。
|
||
|
||
你也可以观看 [这段视频](https://x.com/badlogicgames/status/2041151967695634619), 其中展示了我如何发布我的 `pi-mono` 会话。
|
||
|
||
我会定期在此发布自己的 `pi-mono` 工作会话：
|
||
|
||
- [Hugging Face 上的 badlogicgames/pi-mono](https://huggingface.co/datasets/badlogicgames/pi-mono)
|
||
|
||
## 许可证
|
||
|
||
MIT
|
||
|
||
<p align="center">
|
||
<a href="https://pi.dev">pi.dev</a> 域名由以下方慷慨捐赠
|
||
<br /><br />
|
||
<a href="https://exe.dev"><img src="packages/coding-agent/docs/images/exy.png" alt="Exy mascot" width="48" /><br />exe.dev</a>
|
||
</p>
|