Pi 完整入门教程:安装、配置 DeepSeek 与日常使用

Pi 是一个运行在终端中的轻量级 AI 编程助手。它的核心功能很精简，但可以通过 Extensions、Skills、提示词模板和 Pi Packages 扩展。

这篇教程以 macOS 为例，从安装开始，依次完成模型配置、第一次对话、项目说明、会话管理和扩展能力配置。阅读完后，你应该能够在一个真实项目中安全地使用 Pi。

先了解权限边界 Pi 没有内置沙箱。它可以使用当前系统账号的权限读写文件、执行 Shell 命令；安装的 Extension 也拥有相同权限。不要直接在不可信的仓库或包含重要凭证的环境中运行它。

一、安装 Pi

1. 准备 Node.js 和 npm

先确认电脑已经安装 Node.js 和 npm：

bash

node --version

npm --version

如果终端提示找不到命令，需要先安装 Node.js。完成后再执行下面的安装命令。

2. 全局安装

bash

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts 会禁止依赖包在安装期间执行 preinstall、install、postinstall 等生命周期脚本。Pi 的常规 npm 安装不依赖这些脚本，因此可以使用这个选项减少安装阶段执行第三方脚本的风险。

安装完成后检查版本：

bash

pi --version

如果能看到版本号，说明安装成功。

二、第一次启动

进入准备使用 Pi 的项目目录，再启动它：

bash

cd '/你的项目路径'

pi

第一次启动时，Pi 可能会下载 fd、ripgrep 等辅助程序。如果还没有配置模型，界面会显示 No models available。

这不是安装失败，只表示 Pi 还没有可用的模型凭证。接下来可以选择以下任一方式：

• 使用 /login 登录支持的订阅账号；
• 使用模型服务商提供的 API Key。

本文使用 DeepSeek API Key。

三、配置 DeepSeek API Key

1. 创建 API Key

打开 DeepSeek 开放平台，登录后创建一个 API Key。

API Key 通常只会完整显示一次。请立即保存到密码管理器中，不要把它写入 Git 仓库、聊天记录、截图或公开文档。

2. 在 Pi 中登录

回到 Pi 的交互界面，输入：

text

/login

依次选择：

1. Sign in with an API key
2. DeepSeek
3. 粘贴刚才创建的 API Key

配置成功后，凭证会保存在：

text

~/.pi/agent/auth.json

结构类似下面这样：

json

{

"deepseek":{

"type":"api_key",

"key":"sk-***"

}

}

[!warning] auth.json 包含真实凭证，不要复制到项目目录，也不要提交到 Git。

完成登录后，使用 /model 选择 DeepSeek 模型。当前模型会显示在界面右下角。

3. 可选：通过环境变量提供凭证

如果不希望把 Key 保存到 auth.json，也可以在启动 Pi 前设置环境变量：

bash

export DEEPSEEK_API_KEY='你的 API Key'

pi

这种写法只对当前终端会话生效。不要把包含真实 Key 的命令保存到公开的 Shell 配置或脚本中。

四、开始第一次对话

配置模型后，就可以直接输入任务。例如：

text

请先阅读这个项目的 README 和 package.json，说明项目如何启动。暂时不要修改文件。

Pi 会根据任务调用工具。当前版本的内置工具包括：

早期版本的启动界面可能只列出 read、write、edit 和 bash 四个工具；实际可用工具以本机安装版本和 pi --help 的输出为准。

第一次使用时，建议把任务拆得清楚一些：

text

先分析报错原因，不要修改代码。找到原因后给出修复方案。

确认方案后，再让 Pi 实施并运行测试。这样更容易检查它要做什么。

五、使用 AGENTS.md 提供项目说明

Pi 启动时会自动读取上下文文件。项目根目录中的 AGENTS.md 可以告诉它项目结构、常用命令和协作约定。

一个简单示例：

markdown

# 项目说明

这是一个使用 TypeScript 和 pnpm 的 Web 项目。

## 常用命令

- 安装依赖：`pnpm install`

- 开发环境：`pnpm dev`

- 运行测试：`pnpm test`

- 代码检查：`pnpm lint`

## 修改约定

- 修改前先阅读相关测试。

- 不要修改 `dist/` 中的生成文件。

- 完成后运行与改动相关的测试和 lint。

Pi 会从以下位置加载 AGENTS.md 或 CLAUDE.md：

• ~/.pi/agent/AGENTS.md
  ：所有项目共用的个人说明；
• 当前工作目录的父目录：从上到下查找；
• 当前工作目录：离项目最近的具体说明。

修改上下文文件后，执行 /reload 重新加载，或者退出并重启 Pi。若临时不想加载这些文件，可以用 pi --no-context-files 启动。

六、日常操作

1. 引用文件和图片

在输入框中键入 @，可以模糊搜索项目文件。也可以在启动命令中直接引用：

bash

pi @README.md "总结这个项目，并给出本地启动步骤"

一次引用多个文件：

bash

pi @src/app.ts @src/app.test.ts "检查实现和测试是否一致"

在 macOS 中，可以用 Ctrl+V 粘贴图片，也可以把图片拖入终端。

2. 执行 Shell 命令

在输入内容前加一个 !，Pi 会执行命令，并把输出加入模型上下文：

text

!npm test

如果只想自己查看输出，不希望发送给模型，使用两个感叹号：

text

!!git status

使用 ! 或 !! 都是在本机真实执行命令，仍需留意删除文件、覆盖数据、安装软件等操作。

3. 切换模型和思考等级

• /model
  ：选择当前使用的模型；
• /settings
  ：设置思考等级、主题、消息投递方式等；
• 启动时也可以使用 --model 和 --thinking。

例如：

bash

pi --model deepseek/deepseek-chat --thinking medium

具体模型 ID 可能随服务商目录变化，优先通过 /model 查看本机可选项。

4. 常用斜杠命令

在输入框中键入 /，可以查看当前版本支持的全部命令。

5. 非交互模式

-p（或 --print）用于执行一次任务：输出结果后立即退出，适合脚本和 CI。

bash

pi -p "总结这个代码库"

也可以传入管道内容：

bash

git diff | pi -p "审查这次改动，重点检查 bug 和安全问题"

另外两种模式面向程序集成：

• --mode json
  ：以 JSONL 输出完整事件流，包括回复、工具调用、工具结果和错误；
• --mode rpc
  ：通过标准输入、标准输出与其他进程进行 RPC 通信。

它们不适合普通阅读。如果只是想得到一段文本，使用 -p 即可。

七、管理 Session

Pi 会自动保存会话。默认位置是 ~/.pi/agent/sessions/，并按启动时的工作目录分组。每个 Session 都是一个树形结构的 JSONL 文件，因此同一段历史可以产生多个分支。

1. 启动参数

2. 交互界面中的命令

/tree、/fork 和 /clone 容易混淆，可以这样理解：

八、上下文压缩与分支摘要

模型的上下文窗口有限。会话太长时，Pi 会用摘要代替较早的对话，同时保留最近内容。

摘要只改变下一次发送给模型的上下文，不会删除磁盘中的原始 JSONL 会话记录。

如果希望摘要特别保留某些信息，可以这样执行：

text

/compact 保留已经修改的文件、失败的测试、关键决策和下一步操作

九、项目信任与安全

1. 项目信任会控制什么

当项目中存在下列资源时，Pi 会进行项目信任判断：

• .pi/settings.json
• .pi/extensions/
  、.pi/skills/、.pi/prompts/、.pi/themes/
• .pi/SYSTEM.md
  、.pi/APPEND_SYSTEM.md
• 当前目录或父目录中的 .agents/skills/

单独存在一个空的 .pi/ 目录不会触发判断。

信任项目后，Pi 可以加载项目本地设置、Extensions、Skills、提示词模板、主题、系统提示词和项目 Packages。拒绝信任时，这些受保护资源会被跳过。

AGENTS.override.md、AGENTS.md 和 CLAUDE.md 等上下文文件不受项目信任保护；除非显式关闭上下文加载，否则它们仍会被读取。因此，不可信仓库中的说明文字同样需要谨慎对待。

2. 设置默认信任策略

输入 /settings，找到 Default project trust：

它有三种策略：

• ask
    交互模式中询问是否信任，这是默认值；
• always
    自动信任所有项目本地资源；
• never
    始终跳过项目本地资源。

信任决定保存在 ~/.pi/agent/trust.json 中，并按规范化后的目录路径记录。当前目录没有记录时，Pi 会采用最近父目录的决定。

非交互模式不会弹出询问。当默认值为 ask 或 never，且没有已保存的信任决定时，项目本地资源会被忽略。单次运行可以使用 --approve（-a）或 --no-approve（-na）覆盖信任结果。

3. 信任不等于沙箱

项目信任只决定“启动时是否加载项目本地配置和扩展”，不会限制 read、write、edit、bash 等工具的权限。

处理不可信仓库、无人值守任务或高风险脚本时，建议：

• 在容器、虚拟机或专用沙箱中运行 Pi；
• 只挂载任务需要的目录；
• 只提供必要且尽量短期有效的凭证；
• 不需要联网时限制网络访问；
• 完成后检查 git diff、测试结果和生成文件。

十、Extensions、Skills 与 Pi Packages

1. Extensions：改变 Pi 的运行能力

Extension 是使用 TypeScript 或 JavaScript 编写的扩展模块。它可以注册新工具、新命令、自定义界面，或监听、修改 Pi 的运行事件。

自动加载位置：

• 全局：~/.pi/agent/extensions/*.ts
• 全局目录形式：~/.pi/agent/extensions/*/index.ts
• 项目：.pi/extensions/*.ts
• 项目目录形式：.pi/extensions/*/index.ts

项目 Extensions 只有在项目被信任后才会加载。修改后可以执行 /reload。

临时测试一个本地 Extension：

bash

pi -e ./my-extension.ts

也可以临时加载 npm 或 Git 来源的 Pi Package，不写入长期配置：

bash

pi -e npm:@foo/bar

pi -e git:github.com/user/repo

Extension 是在本机直接运行的代码，拥有当前用户的完整权限。只加载你已经检查并信任的代码。

2. Skills：按需加载的工作流

Skill 是以 Markdown 说明为核心的任务工作流包，也可以附带脚本、参考资料和资源文件。Pi 启动时只读取 Skill 的名称与描述；任务匹配后，模型再读取完整的 SKILL.md。这能避免所有说明一直占用上下文。

常见位置：

• 全局：~/.pi/agent/skills/、~/.agents/skills/
• 项目：.pi/skills/、.agents/skills/
• 单次启动：pi --skill <路径>

项目 Skills 需要先信任项目。第三方 Skill 可能要求模型运行附带脚本，因此安装前同样需要检查内容。

一个最小 Skill 的目录结构：

text

my-skill/

├── SKILL.md

├── scripts/

├── references/

└── assets/

SKILL.md 示例：

markdown

---

name: release-check

description: 发布前检查版本号、测试、构建产物和变更日志。

---

# Release Check

1. 读取 package.json 和变更日志。

2. 运行测试与构建命令。

3. 汇总阻塞发布的问题，不要自动发布。

匹配任务时 Pi 可以自动使用 Skill，也可以显式调用：

text

/skill:release-check

创建或修改 Skill 后执行 /reload。如果不希望自动发现 Skills，使用 --no-skills；即使使用该选项，仍可通过 --skill <路径> 显式加载指定 Skill。

3. Pi Packages：打包和安装扩展资源

Pi Package 可以把 Extensions、Skills、提示词模板和主题组合成一个可安装包。

常用命令：

bash

pi install npm:@foo/bar@1.0.0

pi install git:github.com/user/repo@v1

pi install ./本地包目录

pi list

pi remove npm:@foo/bar

默认安装到个人配置；加 -l 则写入当前项目的 .pi/settings.json：

bash

pi install -l npm:@foo/bar@1.0.0

项目配置可以与团队共享。其他成员信任项目后，Pi 会补装缺少的 Packages。安装第三方 Package 前，应先检查来源及其包含的 Extensions、Skills 和安装依赖。

十一、更新与卸载

更新 Pi 本身：

bash

pi update

更新 Pi、Packages，并同步固定的 Git 引用：

bash

pi update --all

只刷新模型目录：

bash

pi update --models

如果是通过 npm 安装，卸载命令为：

bash

npm uninstall -g @earendil-works/pi-coding-agent

卸载程序不会自动删除 ~/.pi/agent/ 中的凭证、设置和历史 Session。若确实要清理这些数据，请先备份并逐项确认，不要直接删除整个目录。

十二、常见问题

启动后提示 No models available

说明还没有可用凭证。执行 /login 配置订阅账号或 API Key，然后使用 /model 选择模型。

输入 /loin、/setting 没有反应

正确命令分别是 /login 和 /settings。输入 / 可以查看自动补全，避免拼写错误。

修改 AGENTS.md 或 Skill 后没有生效

执行 /reload，或者退出后重新启动 Pi。项目本地 Skill 还需要项目处于信任状态。

不想让一次对话被保存

使用临时会话：

bash

pi --no-session

只想让 Pi 阅读代码，不允许修改

可以限制本次启动的工具：

bash

pi --tools read,grep,find,ls -p "审查代码并报告问题，不要修改文件"

工具白名单可以减少误操作，但 Pi 本身仍不是沙箱。