---

前言

把极简 AI 编程 Agent 变成自己的开发工作台

本文基于 Pi CLI 当前版本整理，覆盖安装、模型配置、图片输入、历史会话、多仓库协作、Prompt Template、Skill、Extension、自动化与安全实践。

---

前言

最近我开始尝试 Pi CLI。

刚上手时，我对它的第一印象是：功能似乎没有 Claude Code、Codex CLI 那么“完整”。没有默认的 Plan Mode，没有内置子 Agent，也没有一层层权限确认弹窗。进入项目后，主要就是让模型使用 read、grep、edit、write 和 bash 等工具分析、修改代码。

继续使用后，我才发现，这种“什么都没替你决定”的设计，反而是 Pi 最有意思的地方。

Pi 更像一个极简的 Agent Harness（智能体运行框架）：核心保持轻量，工作流则通过 AGENTS.md、Prompt Template、Skill 和 TypeScript Extension 自己搭建。你可以把它配置成代码阅读器、跨仓库分析助手、SQL 排查工具、只读 Review Agent，甚至嵌入自己的 Node.js 服务。

这篇文章不只介绍命令，还会结合几个真实问题展开：

• 为什么重新打开 Pi 后看不到之前的对话？
• 切换模型后，上下文和缓存还在不在？
• Pi 到底支不支持图片？
• 前端、后端是多个独立 Git 仓库时，应该从哪里启动？
• Prompt、Skill 和 Extension 分别适合解决什么问题？
• 如何避免 AI 误改 .env、执行危险命令？

---

一、Pi CLI 是什么

Pi 是一个运行在终端中的 AI 编程 Agent。它可以读取项目文件、搜索代码、编辑文件、执行命令，并把模型的推理与工具调用组织成一段可恢复的 Session。

它的设计重点不是“开箱即用地塞入所有功能”，而是提供一个很小的核心，再允许开发者按需要扩展：

能力	作用
Context Files	提供长期有效的项目规则和背景
Prompt Templates	把高频提示词变成斜杠命令
Skills	封装领域知识、工作流、脚本和参考资料
Extensions	增加工具、命令、UI、安全拦截和生命周期逻辑
Packages	打包并安装上述资源
SDK / RPC	将 Pi 嵌入其他应用或自动化流程

Pi 默认不内置 MCP、子 Agent、Plan Mode、Todo List 和权限弹窗。这些能力可以由 Extension 或外部工具提供。

适合 Pi 的场景包括：

• 想使用不同模型，不希望被单一厂商绑定；
• 经常同时阅读前端、后端和公共包；
• 想把团队规范固化为 Agent 工作流；
• 希望用 TypeScript 扩展自己的编程 Agent；
• 需要一个轻量、可组合、可嵌入的终端 Agent。

---

二、安装与第一次启动

1. 安装

macOS、Linux 可以使用 npm：

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

确认版本：

pi --version

更新 Pi：

pi update --self

更新内置模型目录：

pi update --models

2. 进入项目

cd /path/to/project
pi

进入交互界面后，可以使用：

/login

选择支持的订阅服务，或者配置 API Key。例如使用 DeepSeek API：

export DEEPSEEK_API_KEY="你的 API Key"
pi

不要把真实 Key 写进 Git 仓库，也不要直接写进 AGENTS.md。

3. 选择模型

进入 Pi 后：

/model

调整推理强度：

/thinking

限制平时循环切换的模型：

/scoped-models

之后可以通过 Ctrl+P 在选中的模型之间切换。

也可以在启动时指定：

pi --provider deepseek \
  --model deepseek-v4-pro

---

三、先掌握日常高频操作

1. 引用文件

在输入框中键入 @，可以模糊搜索项目文件：

@src/auth/auth.service.ts 分析登录与刷新 Token 的流程

启动时也能携带文件：

pi @src/auth/auth.service.ts \
  "审查这个服务的异常处理"

2. 执行 Shell 命令

!pnpm test

命令结果会发送给模型。如果只想在终端执行，不希望把输出放入模型上下文：

!!git status

3. 工作过程中追加要求

Pi 正在工作时仍然可以输入消息：

• Enter：加入 steering 消息，在当前一轮工具调用结束后调整方向；
• Alt+Enter：加入 follow-up，等当前任务全部完成后继续；
• Escape：停止当前操作，并把排队消息恢复到编辑框；
• Alt+Up：取回排队的消息。

例如 Pi 正在改登录功能时，可以追加：

先不要改数据库结构，保持现有 DTO 兼容。

不需要等它全部结束后重新解释一遍。

---

四、历史会话：关闭终端后不必重新开始

这是我第一次使用时遇到的真实问题：在一个很大的项目目录里和 Pi 对话了很久，关闭后重新打开，却感觉历史记录不见了。

实际上，Pi 会把交互式 Session 自动保存为 JSONL，并按照“启动时的工作目录”分类。默认位置是：

~/.pi/agent/sessions/

如果之前这样启动：

cd ~/projects/wms
pi

后来却在父目录启动：

cd ~/projects
pi

这会被视为两个不同的工作目录，所以看起来像是历史记录消失了。

恢复历史会话

回到原来的准确目录：

cd ~/projects/wms
pwd -P
pi -r

pi -r 会打开历史会话选择器。

直接继续该目录最近一次会话：

pi -c

进入 Pi 后也可以使用：

/resume

查看当前 Session 文件和 Token 信息：

/session

重要任务建议及时命名：

/name WMS出库流程分析

或者启动时命名：

pi --name "WMS 出库流程分析"

哪些情况真的不会保存

如果启动时使用了：

pi --no-session

这就是临时会话，关闭后无法恢复。

更换电脑、系统用户、容器或用户主目录，也可能访问不到原来的 ~/.pi/agent/sessions。

---

五、切换模型后，上下文与缓存分别会怎样

这里最容易混淆两个概念：

1. Session 上下文：由 Pi 保存的对话和工具记录；
2. Prompt Cache：模型服务商在服务端缓存的计算结果。

切换 /model 后，Pi 仍然会把当前 Session 的对话、工具调用、文件读取结果和压缩摘要交给新模型。因此，切换模型不会让新模型突然“失忆”。

但是，API 的 Prompt Cache 通常不会跨模型、跨 Provider 共享：

切换方式	Session 历史	API 缓存
DeepSeek Flash → Pro	保留	不共享，Pro 重新计算
Flash → Pro → Flash	保留	切回后旧前缀可能部分命中
DeepSeek → Codex	保留	完全不共享
同模型继续对话	保留	相同前缀通常可以命中
执行 /compact	保留摘要	原来的完整前缀发生变化

DeepSeek 的 Context Caching 默认自动开启。当后续请求与之前请求拥有完整匹配的前缀单元时，对应部分才会命中缓存。

推荐的多模型分工

不要每问一句就切换一次模型，更好的方式是按阶段分工：

Flash：搜索代码、定位文件、梳理调用链
                     ↓
Pro/Codex：架构判断、复杂修改、调试测试
                     ↓
Flash：整理文档、生成 Commit Message

如果对话已经非常长，切换到昂贵模型前可以手动压缩：

/compact 保留任务目标、关键文件、调用链、已确认结论、
修改计划、测试结果、Git 状态和未解决问题

虽然新模型第一次请求仍然没有旧模型的缓存，但输入会明显变短。

需要注意：Pi 不会为整个代码库建立永久向量索引。之前读过的文件如果还在 Session 上下文中，新模型可以利用；但文件发生修改、上下文被压缩或模型认为信息不足时，仍可能重新读取文件。这通常是正确行为，可以避免根据过期代码继续修改。

---

六、图片输入：Pi 支持，但模型也必须支持

Pi CLI 本身支持图片附件：

• 在终端中拖入图片；
• 使用 Ctrl+V 粘贴图片；
• 通过 @screenshot.png 引用图片；
• 启动时携带图片文件。

例如：

pi -p @screenshot.png \
  "分析这个页面的布局和交互问题"

如果当前模型只支持文本，图片就可能被忽略或返回错误。使用 DeepSeek 时，需要选择支持图片输入的模型：

pi update --models

pi --provider deepseek \
  --model deepseek-v4-flash-vision-exp

UI 开发的稳定做法

不建议让实验性 Vision 模型直接完成所有复杂重构。更稳定的流程是：

1. Vision 模型读取原始截图；
2. 让它输出结构化的 UI 规格；
3. Pro 或 Codex 读取 UI 规格和项目代码完成实现；
4. 再把运行后的截图交给 Vision 对比。

UI 规格可以包含：

- 页面结构
- 容器宽度和间距
- 字号与颜色
- 响应式断点
- 组件层级
- Hover、Loading、Empty 等状态
- 与现有页面的差异

这样既利用了视觉模型，又把复杂代码推理交给更稳定的模型。

---

七、多仓库项目：从共同父目录启动

很多企业项目并不是标准 Monorepo，而是前端、后端各自拥有独立 Git 仓库，例如：

company-workspace/
├── oa-web/       # OA 前端，独立 Git 仓库
├── srm-web/       # SRM 前端，独立 Git 仓库
└── oa-api/        # Java 后端，独立 Git 仓库

如果只在 oa-web 中启动 Pi，它很难主动追踪后端 Controller、Service 和数据库模型。

更合适的方式是：

cd company-workspace
pi

三个子目录仍然可以是三个独立 Git 仓库，不需要为了 AI 工具强行改造成 Monorepo。

一个重要细节

Pi 启动时会自动加载：

• ~/.pi/agent/AGENTS.md；
• 当前工作目录的 AGENTS.md 或 CLAUDE.md；
• 从当前目录向上的父目录 Context Files。

它不会因为当前目录下面有多个子仓库，就自动加载每个子仓库中的 AGENTS.md。

因此，从共同父目录启动时，最好在父目录放一份总入口：

company-workspace/
├── AGENTS.md
├── .pi/
├── oa-web/
├── srm-web/
└── oa-api/

示例：

# Repository Mapping

- oa-web: OA web frontend
- srm-web: SRM frontend
- oa-api: Java backend
- OA backend: oa-api/yudao-module-oa
- SRM backend: oa-api/yudao-module-srm

# Working Rules

- 修改接口前必须追踪前端 API、Controller、Service、DTO 和数据库
- 默认先分析调用链，再修改代码
- 三个目录是独立 Git 仓库
- 不修改 .env，不读取或输出密钥
- 不执行生产数据库操作
- 修改后分别展示每个仓库的 git diff
- 运行与改动范围对应的测试、lint 或 typecheck

# Commands

- OA frontend: cd oa-web && pnpm typecheck
- SRM frontend: cd srm-web && pnpm typecheck
- Backend: cd oa-api && mvn test

修改 Context Files 后执行：

/reload

跨仓库分析提示词

先不要修改任何文件。

分析“手机快捷登录”的完整调用链，依次追踪：

1. 前端登录页面和环境变量
2. API 请求定义
3. 请求与响应 DTO
4. 后端 Controller
5. Service 与权限校验
6. 用户、角色和菜单数据
7. OA 与 SRM 实现之间的差异

最后列出关键文件、风险和推荐修改顺序。

---

八、用 Prompt Template 把提示词变成命令

如果同一种分析每周都要写一次，就不应该继续复制长提示词。

Pi 会加载项目下的：

.pi/prompts/*.md

例如创建 .pi/prompts/trace.md：

---
description: 追踪跨仓库完整调用链
argument-hint: "<功能名称>"
---

分析“$@”的完整调用链。

依次追踪：

1. 前端页面和组件
2. API 请求定义
3. 请求与响应类型
4. 后端 Controller
5. Service 和业务逻辑
6. 数据库实体或 Mapper
7. 权限与状态流转
8. 可能受到影响的其他模块

只分析，不修改文件。最后输出关键文件清单、风险和推荐修改顺序。

重新加载：

/reload

以后可以直接输入：

/trace 创建采购订单
/trace OA首页待办统计
/trace 手机快捷登录

Prompt Template 支持：

写法	含义
$1、$2	第一个、第二个参数
$@	所有参数
${1:-default}	参数为空时使用默认值
${@:2}	从第二个参数开始的所有参数

推荐建立几个高频命令：

/trace       追踪调用链
/review      审查当前 Git Diff
/implement   按确认后的方案实现
/api-change  检查接口变化影响
/debug-sql   系统化分析慢 SQL
/interview   根据当前代码生成面试问答

---

九、AGENTS.md、Prompt、Skill 和 Extension 怎么选

这是理解 Pi 高级玩法的关键。

能力	什么时候使用
AGENTS.md	每次任务都必须遵守的规则和项目地图
Prompt Template	用户手动触发、经常重复的提示词
Skill	一整套领域工作流、资料、脚本和检查清单
Extension	需要真正改变 Pi 行为或增加工具时

1. AGENTS.md：项目宪法

适合放：

• 仓库对应关系；
• 技术栈与启动命令；
• 修改边界；
• 安全规则；
• 必须运行的验证命令。

不要把大量数据库结构、接口文档、历史方案全部塞进去，否则每一轮都会携带大量低价值 Token。

2. Prompt Template：快捷指令

适合“每次内容不同，但处理结构相同”的任务，例如调用链分析、Review、生成提交说明。

3. Skill：领域能力包

例如可以把 Flowable 慢 SQL 排查封装为：

.pi/skills/flowable-debug/
├── SKILL.md
├── references/
│   ├── tables.md
│   └── task-status.md
└── scripts/
    └── explain-sql.sh

SKILL.md 可以规定：

• 先确认运行时表还是历史表；
• 必须检查 EXPLAIN ANALYZE；
• 对比估算行数和实际行数；
• 检查联合索引顺序；
• 禁止直接修改生产数据；
• 最终输出根因、证据、方案、风险和回滚方式。

Pi 启动时主要加载 Skill 的名称和描述，任务匹配后才读取完整内容。这比把所有领域资料塞进 AGENTS.md 更合理。

4. Extension：真正编程扩展 Pi

Extension 是 TypeScript 模块，可以：

• 注册模型可调用的新工具；
• 增加 /plan 等命令；
• 拦截危险 Bash 命令；
• 禁止写入特定目录；
• 在每轮开始前创建 Git Checkpoint；
• 自定义状态栏、弹窗和交互界面；
• 监听 Session、模型切换和工具事件；
• 注册自定义 Provider。

官方示例已经包含：

Extension	作用
permission-gate	危险命令执行前确认
protected-paths	保护 .env、.git、node_modules
dirty-repo-guard	有未提交修改时阻止危险会话操作
plan-mode	提供只读探索和计划跟踪
git-checkpoint	每轮创建可恢复的 Git 检查点
handoff	将上下文交接给新的精简 Session
subagent	将任务分给隔离上下文的子 Agent

对一般项目，推荐的安装优先级是：

protected-paths
→ permission-gate
→ plan-mode
→ git-checkpoint
→ handoff

第三方 Extension 可以在本机执行代码，安装前必须检查源码。

---

十、Session Tree：同时探索多个方案

Pi 的 Session 不是简单的线性聊天记录，而是一棵树。

例如分析一个 384 万行流程变量表的性能问题时，可以先在主分支完成问题定位，然后：

1. 使用 /fork 尝试“增加索引与改写 SQL”；
2. 使用 /tree 回到共同节点；
3. 创建另一个分支尝试“增量统计表”；
4. 比较两个分支的收益、复杂度和一致性风险；
5. 使用 /clone 把最终方向复制成独立 Session；
6. 使用 /compact 压缩不再需要的原始探索过程。

常用命令：

/tree
/fork
/clone
/compact

这比在一条对话中反复说“忽略刚才的方案”更清晰，也适合架构方案对比。

---

十一、只读模式、脚本和 CI

Pi 不只适合交互使用，也能作为一次性命令运行。

1. 只读代码审查

只允许读取和搜索：

pi --tools read,grep,find,ls \
  --no-session \
  -p "审查当前项目，列出安全、类型和错误处理问题"

2. 审查暂存区 Diff

完全禁止工具，只把 Diff 通过标准输入交给模型：

git diff --cached |
pi --no-tools \
  --no-session \
  -p "审查这份 Diff，重点检查回归风险、安全问题和遗漏测试"

3. JSON 事件流

pi --mode json \
  "分析当前代码库"

这适合接入脚本或 CI，因为工具调用、流式内容和结束事件都能以 JSONL 处理。

4. RPC 与 SDK

RPC 模式：

pi --mode rpc

可以通过标准输入输出控制 Pi，适合嵌入 IDE、自定义桌面应用或后台任务。

如果本身就在开发 Node.js/TypeScript 应用，也可以使用 Pi SDK 创建 AgentSession，不一定要启动子进程。

---

十二、安全：Project Trust 不等于沙箱

Pi 的工具和 Extension 默认拥有启动 Pi 的当前系统用户权限。

也就是说，只要当前用户有权限，它理论上可以：

• 读写项目外文件；
• 执行 Shell 命令；
• 读取环境变量；
• 使用本机网络；
• 调用已经登录的开发工具。

Project Trust 只决定是否加载项目本地的 Settings、Skill、Prompt 和 Extension，不会限制模型后续能够执行什么。它不是安全沙箱。

推荐安全习惯

开始任务前检查：

git status

重要修改前建立 Checkpoint：

git add .
git commit -m "checkpoint before pi"

在 AGENTS.md 中明确：

- 禁止修改 .env 和密钥文件
- 禁止执行生产数据库写操作
- 禁止修改 Git 历史
- 禁止执行 rm -rf、sudo 等危险命令
- 未经确认不得安装全局依赖
- 只修改当前任务相关文件

对于陌生仓库、无人值守任务或需要运行不可信代码的情况，应把 Pi 放进 Docker、VM、微型虚拟机或其他系统级隔离环境，并且只挂载必要目录、传入最少的凭据。

---

十三、一套适合企业项目的完整工作流

以“前端 + 后端多仓库修改”为例，可以采用下面的流程。

阶段 1：恢复并命名会话

cd company-workspace
pi -r

/name OA手机快捷登录

阶段 2：先只读分析

/trace 手机快捷登录

要求输出：

• 前端页面入口；
• 环境变量；
• API 请求；
• 后端 Controller、Service；
• 权限和用户模型；
• OA 与 SRM 的实现差异；
• 修改范围和风险。

阶段 3：复杂方案切强模型

/model

切换到 Pro 或 Codex，让它根据分析结果提出实现计划。

阶段 4：确认后实现

按照已确认方案实现。

要求：
1. 保持现有 API 向后兼容；
2. 不修改生产配置；
3. 每完成一个仓库就运行对应检查；
4. 遇到范围扩大时暂停并说明；
5. 最后分别展示每个仓库的 git diff --stat。

阶段 5：验证与交付

检查当前修改：

1. 是否完成原始需求
2. 是否存在类型错误
3. 是否遗漏权限校验
4. 是否影响其他登录方式
5. 是否需要补充测试
6. 给出人工验证步骤
7. 生成 Conventional Commit Message

这一套流程的关键不是提示词写得多漂亮，而是把项目地图、分析、实现、验证和安全边界拆成稳定层次。

---

十四、常见问题排查

1. pi -r 找不到之前的会话

先确认当前物理路径：

pwd -P

回到上次启动 Pi 的准确目录，然后执行：

pi -r

如果之前用了 --no-session，则无法恢复。

2. /model 里没有新模型

pi update --self
pi update --models
pi --list-models deepseek

3. 图片无法识别

确认三件事：

• 当前模型声明支持 image 输入；
• 图片格式受支持；
• 图片已经作为附件传入，而不是只输入了一个模型无法访问的本地路径字符串。

4. 修改了 Prompt 或 AGENTS.md，但没有生效

/reload

5. 切换模型后回答风格或判断变化很大

这是正常现象。Session 历史仍在，但模型能力、工具调用习惯和系统提示兼容性不同。可以先要求旧模型输出阶段总结，再切换模型；长对话则使用带明确要求的 /compact。

6. Pi 频繁重新读取文件

Pi 没有默认建立永久代码库索引。重新读取能确保基于最新文件工作。如果同一批背景资料反复使用，可以把稳定规则放入 AGENTS.md，把领域资料做成 Skill，而不是依赖某次对话中的文件内容。

---

总结

Pi 的入门很简单：安装、登录模型、进入项目、开始对话。

但它真正的价值在高级用法：

1. 用 Session 保存和恢复长期任务；
2. 用不同模型分别完成检索、推理、视觉和整理；
3. 用共同父目录处理多个独立 Git 仓库；
4. 用 AGENTS.md 建立项目规则和仓库地图；
5. 用 Prompt Template 消除重复提示词；
6. 用 Skill 封装领域工作流；
7. 用 Extension 增加安全、工具与交互能力；
8. 用 Session Tree 同时探索多个方案；
9. 用 Print、JSON、RPC 和 SDK 接入自动化；
10. 用 Git 与系统级隔离控制风险。

如果只把 Pi 当成另一个聊天式 CLI，它会显得非常朴素。

如果把自己的项目经验、排查步骤和工程规则逐渐沉淀进去，它就会从一个通用编程 Agent，变成真正适合自己的开发工作台。

---

参考资料

• Pi 官方文档
• Using Pi
• Pi Sessions
• Compaction & Branch Summarization
• Prompt Templates
• Pi Skills
• Pi Extensions
• Pi Security
• Pi Containerization
• Pi RPC Mode
• DeepSeek Context Caching
• DeepSeek Vision