开始之前最好你电脑安装了Windows Terminal 没有的话去安装一下 可以通过 https://apps.microsoft.com/detail/9n0dx20hk701?hl=zh-CN 安装

⚠️安全警告：Pi默认没有沙箱，直接以本机账号权限执行shell命令，不要放任执行高危命令

一、安装Pi Agent

方式1：官方脚本（推荐）

# Linux / macOS
curl -fsSL https://pi.dev/install.sh | sh

# Windows PowerShell
powershell -c "irm https://pi.dev/install.ps1 | iex"

方式2：npm全局安装

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

# 验证安装
pi --version
二、接入DeepSeek（示例）

方法A：交互式/login（最简单，新手优先）

1、终端进入你的项目文件夹，输入 pi 启动交互终端

2、在pi会话内输入：

/login

3、选择enter api key，筛选选择deepseek，粘贴你的API Key回车保存。

4、输入 /model 打开模型选择器，选择 deepseek‑v4‑pro 或 deepseek‑v4‑flash。

方法B：手动配置models.json（高级）

配置文件路径：

  1. Linux/macOS：~/.pi/agent/models.json

  2. Windows：%USERPROFILE%\.pi\agent\models.json

完整配置内容：

{
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com",
      "api": "openai‑completions",
      "apiKey": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek‑v4‑pro",
          "name": "DeepSeek V4 Pro",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 1.74,
            "output": 3.48,
            "cacheRead": 0.145,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        },
        {
          "id": "deepseek‑v4‑flash",
          "name": "DeepSeek V4 Flash",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 0.14,
            "output": 0.28,
            "cacheRead": 0.028,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        }
      ]
    }
  }
}

设置环境变量：

# Linux/macOS
export DEEPSEEK_API_KEY="sk‑xxxx你的key"

# Windows PowerShell
$env:DEEPSEEK_API_KEY="sk‑xxxx你的key"

设置默认模型 settings.json

路径：~/.pi/agent/settings.json

{
  "defaultProvider": "deepseek",
  "defaultModel": "deepseek‑v4‑flash",
  "defaultThinkingLevel": "high"
}

保存后重启pi，默认就使用deepseek模型。

模型选型参考

模型适用场景
deepseek‑v4‑pro复杂重构、架构设计、疑难bug排查，推理强，价格贵
deepseek‑v4‑flash日常写代码、改bug、脚本，速度快成本低，日常首选
三、Pi会话内斜杠命令（/开头）

在pi交互终端内部使用：

命令作用
/login登录配置模型API Key
/model打开模型选择切换器（快捷键Ctrl+L）
/think minimal/low/medium/high/xhigh调整推理思考深度，快捷键Shift+Tab循环切换
/reload重新加载AGENTS.md、扩展、快捷键配置
/hotkeys查看全部快捷键清单（官方）
/clear清空当前会话上下文
/reset完全重置会话，新建会话树分支
/history查看会话历史分支，支持回溯
/tree会话树视图，跳转历史分支；连按两次Esc等价
/export html将会话导出为html文件保存
/quit / exit退出pi终端
/help查看全部内置命令
/install npm:xxx安装扩展包
/list列出已安装扩展
四、完整TUI交互快捷键（重点：补充Ctrl+G等全部高频）

进入pi交互界面生效；可通过/hotkeys随时在程序内查看完整列表；可修改~/.pi/agent/keybindings.json自定义快捷键，/reload生效。

📝 编辑器输入类

快捷键功能说明
Ctrl+G打开外部编辑器（vim/nano/notepad）写大段Prompt，保存退出自动回传内容，非常重要！解决终端多行输入痛点
Shift+Enter输入框内换行；Windows Terminal部分环境失效，就用Ctrl+G
Ctrl+V粘贴图片；Windows用Alt+V粘贴图片
Ctrl+C清空当前输入框；连续按两次直接退出Pi
Ctrl+U删除光标到行首全部文字
Ctrl+K删除光标到行尾全部文字
Tab文件路径自动补全，输入@后唤起文件选择器

🤖 Agent任务控制

快捷键功能说明
Esc中断正在运行的Agent任务；按两次打开会话树/tree
Enter立刻发送输入内容，打断Agent当前执行流
Alt+Enter等待Agent完成当前任务之后，再发送新消息（排队发送）

🧠模型与推理控制

快捷键功能说明
Ctrl+L打开模型选择器，等价/model
Ctrl+P向前循环切换已配置模型
Ctrl+Shift+P向后循环切换模型
Shift+Tab循环切换思考强度thinking level(minimal/low/medium/high/xhigh)

👀界面显示开关

快捷键功能说明
Ctrl+O展开/折叠工具调用bash输出日志
Ctrl+T展开/折叠模型推理思考内容（DeepSeek的thinking块）
Ctrl+X复制AI最后一条完整回复内容到剪贴板

🚪系统退出

快捷键功能说明
Ctrl+D输入框为空时直接退出pi
Ctrl+Z挂起pi进程（类Unix系统，Windows无效）

特殊语法：

!cmd：执行shell，并且把命令输出传给大模型

!!cmd：执行shell，不把输出传给模型，避免日志污染上下文，例 !!npm run dev

五、三种运行模式

1）交互式TUI（默认，直接输入pi）

cd 你的项目目录
pi

进入终端对话，直接写需求，Agent会读文件、修改代码、跑shell。

2）Print单次执行模式（-p，脚本调用）

不进入交互，执行任务直接输出结果退出，适合shell脚本调用。

pi -p "帮我写一个python读取csv脚本"
# 引用文件
pi -p @src/main.py "审查这段代码的bug"
# JSON事件流输出，程序解析
pi -p "分析项目结构" --mode json

3）RPC模式

供其他程序通过标准输入输出调用Pi，用于二次开发集成。

六、AGENTS.md 项目提示词 （非常实用）

在你的项目根目录新建AGENTS.md，pi启动自动加载，定义项目编码规范、约束、安全规则，不需要每次对话重复说明要求。

示例模板：

# AGENTS.md 项目规则
## 编码规范
1. 使用TypeScript严格模式，代码简洁，不要多余注释。
2. 修改代码之后优先运行npm run lint检查。
3. 不要修改.env配置文件。

## 安全约束
1. 禁止执行rm‑rf、格式化磁盘等高风险命令。
2. 涉及数据库操作，先输出SQL预览，确认后再执行。

## 输出要求
- 修改文件时，只输出关键改动，不要打印完整大文件。

修改完成，pi会话输入 /reload 立刻生效，不需要重启pi。

全局AGENTS.md：~/.pi/agent/AGENTS.md，对全部项目生效。

七、扩展包安装（内核无内置高级功能）

Pi内核只保留read/write/edit/bash，计划模式、权限弹窗、MCP 、联网能力全部依靠扩展安装。

# 安装扩展
pi install npm:@juicesharp/rpiv‑ask‑user‑question # 权限确认弹窗扩展（强烈推荐，防止乱执行命令）
pi install npm:pi‑mcp‑adapter # MCP协议支持
pi install npm:pi‑web‑access # 联网搜索能力

# 查看已安装扩展
pi list

# 更新全部扩展
pi update --extensions

# 卸载
pi remove npm:xxx
八、常见问题排查

  1. 提示没有可用模型：执行/login确认API Key正确，环境变量是否导出成功。

  2. DeepSeek推理内容不显示：确认models.json中compat配置完整，开启thinkingFormat:"deepseek"。

  3. 修改AGENTS.md/快捷键配置不生效：会话输入 /reload。

  4. 想禁止Agent自动执行shell：安装rpiv‑ask‑user‑question权限弹窗扩展，每次执行命令会先询问确认。

  5. 不要直接把API key明文写死models.json，优先环境变量或/login保存。

  6. 多行输入Shift+Enter无效：直接用Ctrl+G唤起外部编辑器写长提示词，兼容性最好。

九、快速上手示例流程
#1.进入项目目录
cd ~/my‑demo‑project
#2.设置环境变量（方法B才需要，/login方式不用）
export DEEPSEEK_API_KEY="sk‑xxxx"
#3.启动pi
pi
#4.切换模型
/model
#5.写需求（写很长的prompt按 Ctrl+G 打开编辑器）
帮我写一个简单的flask接口，返回json，保存到app.py
#6.任务中途想停止按Esc
#7.退出
/quit

自定义快捷键：编辑 ~/.pi/agent/keybindings.json，改完/reload就生效，不需要重启pi。