Py Bun

PyBun（Python捆绑包）

🐍 The Agent-First Python Runtime 🤖

pip + venv + test runner + MCP server — all in one Rust binary.

Built for AI agents (JSON-first) and humans alike.

Video Demo • Quick Start • Why PyBun? • MCP Server • Commands • Roadmap

______________________________________________________________________

视频演示

______________________________________________________________________

快速开始


macOS/Linux：

curl -LsSf https://raw.githubusercontent.com/VOID-TECHNOLOGY-INC/PyBun/main/scripts/install.sh | sh

Windows（PowerShell）：

irm https://raw.githubusercontent.com/VOID-TECHNOLOGY-INC/PyBun/main/scripts/install.ps1 | iex

或者通过pip/pipx(PyPI):

pipx install pybun-cli
# or
pip install pybun-cli

然后运行：

pybun add requests
pybun run -c -- "import requests; print('Hello, PyBun!')"

______________________________________________________________________

为什么是皮本？

现有的Python工具是为 人类.PyBun是为 人工智能代理和人类.

✨ 关键差异化因素

• 🤖 人工智能原生 每个命令都支持 --format=json 作为一等公民。LLM可以可靠地解析输出，而不需要脆弱的正则表达式。
• 🔌 MCP服务器内置： MCP（模型上下文协议） 让Cursor和Claude Desktop等AI工具直接操作您的Python环境，无需额外设置。
• ⚡ 锈蚀速度： 极快的依赖关系解析和安装。
• 🛡️ 沙盒模式： 使用以下工具安全运行不受信任的AI生成代码 --sandbox.
• 📦 单二进制： 没有依赖关系。只需下载并运行。

💡 示例：AI代理工作流

# AI agent asks: "Install pandas and show the version"
$ pybun --format=json add pandas
{"status": "ok", "detail": {"added": ["pandas==2.2.0"], ...}}

$ pybun --format=json run -c -- "import pandas; print(pandas.__version__)"
{"status": "ok", "stdout": "2.2.0\n", ...}

AI接收结构化的JSON，不需要正则表达式解析。

______________________________________________________________________

状态

• 当前： M1（快速安装程序）、M2（运行时优化）和M4（MCP/JSON）部分稳定。

- pybun install / pybun x （带uv后端）/ pybun runs 是 稳定. - pybun watch （本地）/ pybun test （包装）是 预览. - Windows支持是 预览.

• 平台： macOS/Linux（arm64/amd64），Windows（预览版）

有关功能成熟度（存根/预览/稳定）和分阶段推出策略，请参阅 docs/SPECS.md.

______________________________________________________________________

安装

安装PyBun的最简单方法：

pip install pybun-cli

Other installation methods

macOS/Linux（shell脚本）：

curl -LsSf https://raw.githubusercontent.com/VOID-TECHNOLOGY-INC/PyBun/main/scripts/install.sh | sh

Windows（PowerShell）：

irm https://raw.githubusercontent.com/VOID-TECHNOLOGY-INC/PyBun/main/scripts/install.ps1 | iex

来源：

cargo install --path .

注： 如果您的PATH解析 pybun 到 包子，使用 pybun-cli 相反。

命令参考

包管理

# Install dependencies (generates lockfile)
pybun install --require requests==2.31.0 --index fixtures/index.json

# Add a package (updates pyproject.toml)
pybun add requests

# Remove a package
pybun remove requests

脚本执行

# Run a Python script
pybun run script.py

# Run with arguments
pybun run script.py -- arg1 arg2

# Run inline code
pybun run -c -- "import sys; print(sys.version)"

# Run with profile
pybun run --profile=prod script.py

还支持PEP 723内联元数据：

# /// script
# requires-python = ">=3.11"
# dependencies = ["requests>=2.28"]
# ///
import requests

※目前， 元数据解析和显示是主要功能（预览），计划分阶段推出自动安装和隔离环境执行（请参见 docs/PLAN.md 详细信息）。

临时执行(pybun x)

在临时环境中安装一个包并执行它（Python版本 npx). 如果 uv 如果可用，它用于更快地创建环境。

# Temporarily install and run cowsay
# (Use -t flag for Python cowsay package)
pybun x cowsay -- -t "Hello"

# Specify version
pybun x cowsay==6.1

# With arguments
pybun x black -- --check .

Python版本管理

# Show installed versions
pybun python list

# Show all available versions
pybun python list --all

# Install Python
pybun python install 3.12

# Remove Python
pybun python remove 3.12

# Show Python path
pybun python which
pybun python which 3.11

运行时优化

模块查找器

基于Rust的高速模块搜索：

# Find a module
pybun module-find os.path

# Scan a directory for all modules
pybun module-find --scan -p ./src

# With benchmark
pybun module-find --benchmark os.path

延迟导入

# Show configuration
pybun lazy-import --show-config

# Check module decision
pybun lazy-import --check numpy

# Generate Python code
pybun lazy-import --generate -o lazy_setup.py

# Specify allow/deny lists
pybun lazy-import --allow mymodule --deny debug_tools --generate

文件监视（开发模式）

# Watch for file changes and re-run (currently preview)
# Native watching is planned for phased rollout. For now, use --shell-command (external watcher).
pybun watch main.py

# Watch a specific directory
pybun watch main.py -p src

# Show configuration
pybun watch --show-config

# Generate shell command for external watcher
pybun watch --shell-command main.py

配置文件管理

# Show available profiles
pybun profile --list

# Show profile settings
pybun profile dev --show

# Compare profiles
pybun profile dev --compare prod

# Export profile
pybun profile prod -o prod-config.toml

配置文件：

• dev：启用热重载，详细日志记录
• prod：启用延迟导入，优化
• benchmark：跟踪和定时测量

MCP服务器

用于AI代理的MCP服务器：

# Start in stdio mode
pybun mcp serve --stdio

工具： pybun_resolve, pybun_install, pybun_run, pybun_gc, pybun_doctor\ 资源： pybun://cache/info, pybun://env/info

※目前 pybun_gc, pybun_doctor, pybun_run, pybun_resolve，资源可用. pybun_install 通过解析生成锁文件。HTTP模式尚未实现。

诊断和维护

# Environment diagnostics
pybun doctor
pybun doctor --verbose

# Cache garbage collection
pybun gc
pybun gc --max-size 1G
pybun gc --dry-run

# Self-update check
pybun self update --dry-run
pybun self update --channel nightly

沙盒使用

使用沙箱处理不受信任的脚本或PEP 723代码段：

pybun --format=json run --sandbox examples/hello.py
pybun --format=json run --sandbox --allow-network -c "print('net ok')"

沙盒隔离文件和网络访问；添加 --allow-network 只有在需要的时候。与…结合 --profile=prod 用于类似生产的运行。

档案

配置文件调整性能与开发人体工程学的默认值：

• dev （默认）：启用热重载，详细日志记录。
• prod：启用了延迟导入和优化，输出更安静。
• benchmark：用于可重复基准测试的稳定计时/记录。

示例：

pybun profile --list
pybun run --profile=prod app.py
pybun test --profile=benchmark --format=json

MCP服务器（stdio）

将PyBun作为代理/IDE的MCP服务器进行操作：

pybun mcp serve --stdio
pybun --format=json mcp serve --stdio  # JSON envelope for tooling

工具： pybun_resolve, pybun_install, pybun_run, pybun_gc, pybun_doctor.资源： pybun://cache/info, pybun://env/info.

配置（克劳德桌面）

添加到您的 claude_desktop_config.json:

选项1：使用 uvx （无需安装）

{
  "mcpServers": {
    "pybun": {
      "command": "uvx",
      "args": [
        "--from",
        "pybun-cli",
        "pybun",
        "mcp",
        "serve",
        "--stdio"
      ]
    }
  }
}

选项2：使用pip安装

需要 pip install pybun-cli.

{
  "mcpServers": {
    "pybun": {
      "command": "pybun",
      "args": [
        "mcp",
        "serve",
        "--stdio"
      ]
    }
  }
}

*注：如果 pybun 如果路径不在PATH中。， /Users/username/bin/pybun).*

JSON输出示例

所有命令都支持 --format=json 选项（模式v1）。示例：

pybun --format=json run -c -- "print('hello')"

{
  "version": "1",
  "command": "pybun run",
  "status": "ok",
  "detail": {
    "summary": "executed inline code"
  },
  "events": [],
  "diagnostics": []
}

故障示例：

pybun --format=json run missing.py

{
  "version": "1",
  "command": "pybun run",
  "status": "error",
  "diagnostics": [
    {
      "kind": "runtime",
      "message": "missing.py not found",
      "hint": "pass -c for inline code or a valid path"
    }
  ]
}

测试/构建生成结构化摘要（通过/失败计数、分片信息），同时保持相同的信封：

pybun --format=json test --fail-fast
pybun --format=json build

启用调试跟踪ID：

PYBUN_TRACE=1 pybun --format=json run script.py

环境变量

发行说明自动化

• 从标签生成GA发行说明：\

python scripts/release/generate_release_notes.py --repo . --previous-tag v0.1.0 --tag v0.2.0 --notes-output release/RELEASE_NOTES.md --changelog CHANGELOG.md

• 将注释附在发布清单上（由安装人员提供/通过以下方式自我更新 release_notes JSON格式）：\

python scripts/release/generate_manifest.py --assets-dir release --version 0.2.0 --channel stable --base-url https://github.com/VOID-TECHNOLOGY-INC/PyBun/releases/download/v0.2.0 --output pybun-release.json --release-notes release/RELEASE_NOTES.md

• CI友好的JSON摘要： python scripts/release/generate_release_notes.py --repo . --previous-tag v0.1.0 --tag v0.2.0 --format json

升级指南

看 docs/UPGRADE.md GA前→ GA迁移说明、突破性更改和推荐的CI检查（doc-lint/link+发布说明自动化）。

发展

需求

• 防锈稳定(rustup, cargo)

基本命令

# Format
cargo fmt

# Lint
cargo clippy --all-targets --all-features -- -D warnings

# Test
cargo test

# Development scripts
./scripts/dev fmt
./scripts/dev lint
./scripts/dev test

测试

# All tests
cargo test

# Specific tests
cargo test cli_smoke
cargo test json_schema
cargo test mcp

路线图

• \[x\] M0：存储库和CI支架
• \[x\] M1：快速安装程序（锁文件、解析器、PEP 723）
• \[x\] M2：运行时优化（模块查找、延迟导入、热重新加载）
• \[\]M3：测试运行器（发现、并行执行、快照）
• \[x\] M4:JSON/MCP和诊断
• \[\]M5：建筑商和安全
• \[\]M6：远程缓存、工作区

看 docs/PLAN.md 了解详情。

隐私和遥测

皮本确实如此 不 默认情况下收集遥测数据（选择加入模型）。

# Check telemetry status
pybun telemetry status

# Enable telemetry
pybun telemetry enable

# Disable telemetry
pybun telemetry disable

收集的数据（启用时）：

• 命令使用（匿名）
• 错误诊断
• 性能指标

从未收集： API密钥、令牌、凭据、密码或文件内容。

环境覆盖： PYBUN_TELEMETRY=0|1

许可证

麻省理工学院