Pi Coding Agent

• 学完本教程后，你将能使用 Pi Coding Agent 在终端中完成代码生成、文件编辑、项目调试等任务，无需离开命令行界面。
• 本教程面向已具备基本终端操作经验的开发者，假设你已安装 Python 3.8+ 和 Node.js 16+。

前置条件

• 操作系统：macOS 12+、Linux（Ubuntu 20.04+）或 Windows 10+（需 WSL2）
• 终端：支持 ANSI 转义序列的终端（如 iTerm2、Windows Terminal、GNOME Terminal）
• 网络：可访问 GitHub 和 PyPI/NPM 源
• 账号：无，Pi Coding Agent 完全本地运行

安装与初始化

步骤 1：安装 Pi Coding Agent

• 预期结果：终端显示安装成功信息，无报错。
• 注意事项：若使用 pip，建议在虚拟环境中安装；若使用 npm，确保 Node.js 版本 ≥ 16。

步骤 2：验证安装

pi --version

• 预期结果：输出类似 pi-coding-agent v1.2.3 的版本号。
• 失败排查：若提示“command not found”，检查 PATH 是否包含安装目录。

步骤 3：初始化工作目录

cd /path/to/your/project
pi init

• 预期结果：项目目录下生成 .pi 文件夹，包含默认配置文件 config.yaml。
• 注意事项：pi init 不会覆盖已有 .pi 目录，如需重新初始化，先删除 .pi 文件夹。

核心功能操作

生成代码文件

• 在终端中执行：

  pi generate "创建一个 Flask API，包含 GET /hello 端点，返回 JSON 格式的问候语"

• 预期结果：Pi 在项目目录下生成 app.py 文件，内容包含完整的 Flask 应用代码。
• 注意事项：描述越具体，生成结果越准确。可指定文件名（如 pi generate "app.py: 一个 Flask API..."）。

编辑现有代码

• 在终端中执行：

  pi edit "将 app.py 中的 GET /hello 改为 POST /hello，并添加请求体验证"

• 预期结果：app.py 被修改，GET /hello 变为 POST /hello，并新增请求体验证逻辑。
• 失败排查：若 Pi 提示“无法解析文件结构”，确保文件语法正确（无未闭合括号等）。

调试与运行

• 在终端中执行：

  pi run "python app.py"

• 预期结果：Pi 启动 app.py，并在终端实时显示输出日志。
• 注意事项：pi run 会拦截标准输出，若需直接运行，使用 pi exec "python app.py"。

项目级操作

• 在终端中执行：

  pi refactor "将项目中的函数从同步改为异步，使用 asyncio 和 aiohttp"

• 预期结果：Pi 扫描项目所有 .py 文件，识别并修改同步函数为异步版本，自动添加 async/await 关键字。
• 适用边界：仅支持 Python 和 JavaScript 项目；对于大型项目（>100 文件），建议先指定范围（如 --scope src/）。

常见问题

进阶配置

• 自定义模型：在 .pi/config.yaml 中设置 model: gpt-4 或 model: claude-3（需对应 API Key）。
• 禁用自动格式化：在配置文件中设置 format: false，Pi 将不修改代码缩进和风格。
• 设置代理：若网络受限，在配置文件中添加 proxy: http://127.0.0.1:7890。

卸载

• 根据安装方式执行对应命令：
• pip: pip uninstall pi-coding-agent
• npm: npm uninstall -g pi-coding-agent
• brew: brew uninstall pi-coding-agent
• 预期结果：终端提示卸载成功，删除 .pi 文件夹（可选）以清理所有配置。