diff --git a/README.md b/README.md index 130a412..32febd7 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ + +> [!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 文件为准。 +

pi logo @@ -8,47 +14,47 @@ npm

-> New issues and PRs from new contributors are auto-closed by default. Maintainers review auto-closed issues daily. See [CONTRIBUTING.md](CONTRIBUTING.md). +> 默认情况下，新贡献者提交的新 issue 和 PR 会自动关闭。维护者会每日审查被自动关闭的 issue。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 # Pi Agent Harness -This is the home of the Pi agent harness project including our self extensible coding agent. +这是 Pi agent harness 项目的主仓库，其中包含我们的可自扩展编码 agent。 -* **[@earendil-works/pi-coding-agent](packages/coding-agent)**: Interactive coding agent CLI -* **[@earendil-works/pi-agent-core](packages/agent)**: Agent runtime with tool calling and state management -* **[@earendil-works/pi-ai](packages/ai)**: Unified multi-provider LLM API (OpenAI, Anthropic, Google, …) +* **[@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 等） -To learn more about Pi: +了解更多关于 Pi 的信息： -* [Visit pi.dev](https://pi.dev), the project website with demos -* [Read the documentation](https://pi.dev/docs/latest), but you can also ask the agent to explain itself +* [访问 pi.dev](https://pi.dev), 项目官网，含演示 demo +* [阅读文档](https://pi.dev/docs/latest), 你也可以让 agent 自行讲解 -## All Packages +## 所有软件包 -| Package | Description | +| 软件包 | 说明 | |---------|-------------| -| **[@earendil-works/pi-ai](packages/ai)** | Unified multi-provider LLM API (OpenAI, Anthropic, Google, etc.) | -| **[@earendil-works/pi-agent-core](packages/agent)** | Agent runtime with tool calling and state management | -| **[@earendil-works/pi-coding-agent](packages/coding-agent)** | Interactive coding agent CLI | -| **[@earendil-works/pi-tui](packages/tui)** | Terminal UI library with differential rendering | +| **[@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 库 | -For Slack/chat automation and workflows see [earendil-works/pi-chat](https://github.com/earendil-works/pi-chat). +有关 Slack/聊天自动化与工作流，请参阅 [earendil-works/pi-chat](https://github.com/earendil-works/pi-chat). -## Permissions & Containerization +## 权限与容器化 -Pi does not include a built-in permission system for restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it. +Pi 不包含用于限制文件系统、进程、网络或凭证访问的内置权限系统。默认情况下，它以启动它的用户和进程的权限运行。 -If you need stronger boundaries, containerize or sandbox Pi. See [packages/coding-agent/docs/containerization.md](packages/coding-agent/docs/containerization.md) for three patterns: +若需要更强的隔离边界，请对 Pi 进行容器化或沙箱化。有关三种模式，请参阅 [packages/coding-agent/docs/containerization.md](packages/coding-agent/docs/containerization.md)： -- **Gondolin extension**: keep `pi` and provider auth on the host while routing built-in tools and `!` commands into a local Linux micro-VM. -- **Plain Docker**: run the whole `pi` process in a local container for simple isolation. -- **OpenShell**: run the whole `pi` process in a policy-controlled sandbox. +- **Gondolin extension**：将 `pi` 和提供商认证保留在宿主机上，同时将内置工具和 `!` 命令路由到本地 Linux 微型虚拟机中。 +- **Plain Docker**：在本地容器中运行整个 `pi` 进程，以实现简单隔离。 +- **OpenShell**：在策略控制的沙箱中运行整个 `pi` 进程。 -## Contributing +## 贡献 -See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines and [AGENTS.md](AGENTS.md) for project-specific rules (for both humans and agents). Longer term plans for Pi can also be found in [RFCs](https://rfc.earendil.com/keyword/pi/). +贡献指南请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)，项目特定规则（适用于人类与 agent）请参阅 [AGENTS.md](AGENTS.md)。Pi 的更长期计划也可在 [RFCs](https://rfc.earendil.com/keyword/pi/). -## Development +## 开发 ```bash npm install --ignore-scripts # Install all dependencies without running lifecycle scripts @@ -58,42 +64,42 @@ npm run check # Lint, format, and type check ./pi-test.sh # Run pi from sources (can be run from any directory) ``` -## Supply-chain hardening +## 供应链加固 -We treat npm dependency changes as reviewed code changes. +我们将 npm 依赖变更视为经审查的代码变更。 -- Direct external dependencies are pinned to exact versions. Internal workspace packages remain version-ranged. -- `.npmrc` sets `save-exact=true` and `min-release-age=2` to avoid same-day dependency releases during npm resolution. -- `package-lock.json` is the dependency ground truth. Pre-commit blocks accidental lockfile commits unless `PI_ALLOW_LOCKFILE_CHANGE=1` is set. -- `npm run check` verifies pinned direct deps, native TypeScript import compatibility, and the generated coding-agent shrinkwrap. -- The published CLI package includes `packages/coding-agent/npm-shrinkwrap.json`, generated from the root lockfile, to pin transitive deps for npm users. -- Release smoke tests use `npm run release:local` to build, pack, and create isolated npm and Bun installs outside the repo before tagging a release. -- Local release installs, documented npm installs, and `pi update --self` use `--ignore-scripts` where supported. -- CI installs with `npm ci --ignore-scripts`, and a scheduled GitHub workflow runs `npm audit --omit=dev` plus `npm audit signatures --omit=dev`. -- Shrinkwrap generation has an explicit allowlist for dependency lifecycle scripts; new lifecycle-script deps fail checks until reviewed. +- 直接外部依赖锁定为精确版本。内部 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 脚本依赖在通过审查前会导致检查失败。 -## Share your OSS coding agent sessions +## 分享你的开源编码 agent 会话 -If you use Pi or other coding agents for open source work, please share your sessions. +如果你在开源工作中使用 Pi 或其他编码 agent，请分享你的会话。 -Public OSS session data helps improve coding agents with real-world tasks, tool use, failures, and fixes instead of toy benchmarks. +公开的开源会话数据有助于用真实世界的任务、工具使用、失败与修复来改进编码 agent，而非仅依赖玩具基准测试。 -For the full explanation, see [this post on X](https://x.com/badlogicgames/status/2037811643774652911). +完整说明请参阅 [X 上的这篇帖子](https://x.com/badlogicgames/status/2037811643774652911). -To publish sessions, use [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). Read its README.md for setup instructions. All you need is a Hugging Face account, the Hugging Face CLI, and `pi-share-hf`. +要发布会话，请使用 [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). 阅读其 README.md 了解设置说明。你只需要 Hugging Face 账户、Hugging Face CLI 以及 `pi-share-hf`。 -You can also watch [this video](https://x.com/badlogicgames/status/2041151967695634619), where I show how I publish my `pi-mono` sessions. +你也可以观看 [这段视频](https://x.com/badlogicgames/status/2041151967695634619), 其中展示了我如何发布我的 `pi-mono` 会话。 -I regularly publish my own `pi-mono` work sessions here: +我会定期在此发布自己的 `pi-mono` 工作会话： -- [badlogicgames/pi-mono on Hugging Face](https://huggingface.co/datasets/badlogicgames/pi-mono) +- [Hugging Face 上的 badlogicgames/pi-mono](https://huggingface.co/datasets/badlogicgames/pi-mono) -## License +## 许可证 MIT

- pi.dev domain graciously donated by + pi.dev 域名由以下方慷慨捐赠

Exy mascot
exe.dev