第一次对话：从 hello 到改代码

启动 pi

装好 pi 之后，打开终端，cd 到你想让 pi 工作的项目目录：

cd ~/my-project
pi

第一次启动，pi 会弹出一个项目信任提示——本质上在问你：“这目录里有 .pi/settings.json 和项目级扩展，我能加载它们吗？” 是你自己的项目就选 yes。这个决策会存到 ~/.pi/agent/trust.json，下次不问了。

成功启动后，终端变成一个四区界面：

• 启动头部（顶部）：快捷键提示、pi 加载了哪些上下文文件（AGENTS.md / CLAUDE.md）、skills、扩展
• 消息区（中部）：你和 pi 的对话内容，包括 AI 回复、工具调用详情、通知和报错
• 编辑区（底部输入行）：你打字的地方，边框颜色表示当前推理等级
• 状态栏（最下方）：当前目录、会话名、token / 缓存用量、费用、模型名，总额含 AI 回复、工具上报和摘要生成消耗

第一条对话：让 pi 看看你的项目

在编辑区输入你的第一条指令，回车：

帮我看看这个项目的目录结构和主要功能

pi 会从内置工具集里选最合适的来完成。它的默认工具有这些：

工具	做什么	典型用法
read	读文件内容	读 README.md 了解项目说明
write	创建或覆盖文件	新建一个源文件
edit	精确替换文件中的代码	改某个函数里的几行
bash	执行 shell 命令	跑 ls、npm test、git diff
grep	搜索文件内容	全局搜索函数引用
find	按文件名搜索	找到所有 .ts 文件
ls	列出目录内容	浏览项目结构

你会看到 pi 一步步做了什么——它调了哪个工具、读了哪个文件、执行了什么命令。整个过程是透明可见的。

pi 读完项目结构后会在消息区回复一段总结。如果你的项目有 README.md、package.json 这类文件，pi 会自动读取，不需要你手动指定。

怎么引用文件

你可以在对话中精确指定文件。两种方式。

@ 语法：编辑器内搜索

在编辑区输入 @，pi 自动弹出项目文件的模糊搜索列表：

@src/utils.ts 这个文件里的工具函数都是干什么的

继续打字缩小搜索范围，回车选中。

命令行参数

启动 pi 时直接把文件当参数传进去：

pi @README.md "总结一下这个文档"
pi @src/app.ts @src/test.ts "对比这两个文件的逻辑"
pi -p @screenshot.png "这张截图里显示了什么"

@ 引用支持图片文件，pi 会把图片内容发给模型分析。

让 pi 动手改代码

读完项目结构后，让 pi 干活。比如给一个函数加上错误处理：

@src/api.ts 把 fetchUser 函数包一层 try-catch，网络错误时返回 null 不要崩溃

pi 会这样一步步做：

1. 用 read 读 src/api.ts，定位 fetchUser 函数
2. 用 edit 精确替换那几行代码，包上 try-catch
3. 可能再用 bash 跑一遍构建确认没改坏东西

每一步你都能在消息区看到——pi 具体改了哪几行、构建输出是什么。

改完后 pi 会在消息区高亮显示 diff：增加了什么、删除了什么。满意的话代码已经写入了；不满意就拿 git 撤销（git checkout -- <file>）。

pi 会反问你什么

pi 不是盲目执行机器。遇到不确定的情况，它会反问你：

• 目标模糊：你说”帮我改一下这个页面”，pi 会追问”你想改样式、逻辑还是文案？”
• 多方案需要选择：pi 会列出几个可行的方案让你挑
• AGENTS.md 里写了限制：比如”代码改动后先问过再跑构建”，pi 会照做

对话中的实用操作

复制 pi 的回复

按 Ctrl+X 复制 pi 最后一条回复到剪贴板。比鼠标拖选快得多。

退出对话

编辑区为空时按 Ctrl+D 退出。或者输入 /quit 直接退出。

会话会自动保存到 ~/.pi/agent/sessions/。下次用 pi -c 就能接着聊：

pi -c              # 继续最近一次会话
pi -r              # 浏览历史会话，选一个恢复
pi --name "重构"    # 给会话取个名字
pi --no-session    # 临时用，不保存

在会话里也可以用 /new 开新对话、/resume 恢复旧对话、/name 重构 给当前会话命名。