小白学 AI Agent 第 1 期：在 Windows 上把 Pi 跑起来

很多人听过 AI Agent，却说不清它和普通聊天机器人有什么区别。更别说自己装一个、让它读文件、跑命令、改代码。

这套系列就从一个小白能完成的目标开始：在 Windows 电脑上安装 Pi，打开第一次 Agent 对话，弄明白它到底做了什么。

这一期不追求把所有功能讲完。先建立一张地图，再把第一个工具跑起来。

先定一个学习节奏：预计 8 期

我会把 Pi 拆成 8 个小台阶，每一期只解决一组问题：

认识 Agent，完成 Windows 安装：弄清模型、 Agent 、工具的关系，启动 Pi，完成第一次对话。
认识 Pi 的界面和模型：学会 /login、/model、/settings，知道订阅和 API Key 的区别。
认识工具调用：理解 read、write、edit、bash，让 Pi 读取文件、修改文件、运行检查命令。
认识上下文和会话：学习工作目录、AGENTS.md、会话保存、继续任务和分支。
认识 Skill 和提示模板：把重复的工作整理成可以复用的能力。
认识 Extension 和 Pi Package：给 Pi 增加命令、界面和第三方扩展。
做一个完整的小项目：从需求、文件操作到检查结果，跑通一条实际工作流。
补上安全和进阶能力：项目信任、沙箱、权限边界，以及 print 、 JSON 、 RPC 和 SDK 模式。

这 8 期结束后，你至少应该能回答三件事：Agent 能做什么，哪些动作需要你确认，以及一个需求应该交给模型、工具还是你自己判断。

先把几个词说清楚

模型是什么

模型负责理解你的文字，生成回答，也负责决定下一步要不要调用工具。 Claude 、 GPT 、 Gemini 这类名称，通常指不同的模型或模型服务。

模型本身只能输出文字。它想读取电脑里的文件、执行命令，就需要外部工具。

Agent 是什么

Agent 可以理解成一套工作循环：

读取你的任务。
判断下一步需要什么信息。
调用工具读取文件或执行操作。
查看工具返回的结果。
继续判断，直到完成任务或需要你确认。

所以 Agent 不只是“回答问题”。它会在允许的范围内动手做事。

Pi 是什么

Pi 是一个运行在终端里的 coding agent 。它把模型、工具、会话和扩展接在一起，默认提供 read、write、edit、bash 四个工具：

read：读取文件。
write：创建或覆盖文件。
edit：修改文件。
bash：运行命令。

Pi 的特点是很小、很容易扩展。它没有把子 Agent 、计划模式等功能全部塞进默认体验，而是允许使用 Skill 、 Extension 和 Pi Package 自己搭工作流。

这里要特别提醒一句：Pi 默认使用启动它的用户权限。它没有内置一套完整的文件、进程、网络和凭据限制系统。第一次练习时，建议新建一个空文件夹，里面只放测试文件，不要直接对重要资料夹动手。

Windows 需要准备什么

按照项目当前文档，Windows 用户需要准备：

Windows 10 或 Windows 11 。
Node.js 22.19.0 或更高版本。项目当前 npm 包版本为 0.84.2，要求 Node.js >=22.19.0。
Git for Windows 。 Pi 在 Windows 上需要 Bash，项目文档把 Git Bash 列为最简单的选择。
一个模型服务的登录方式。本系列以 DeepSeek V4 Flash 为例，可以准备 DeepSeek API Key 。 Pi 当前仓库已经把 DeepSeek 列为内置 OpenAI 兼容服务商，并提供 DEEPSEEK_API_KEY 认证方式。模型调用通常会产生费用，具体取决于服务商当前的计费规则。

如果你只想先试用，建议把 Node.js 和 Git Bash 装好，模型登录这一步等 Pi 启动后再选。

第一步：安装 Node.js

打开 Node.js 官网，下载适合 Windows 的 LTS 版本，安装时保持默认选项即可。

安装结束后，打开 Windows Terminal 、 PowerShell 或命令提示符，输入：

node --version
npm --version

如果能看到版本号，说明 Node.js 和 npm 已经进入系统路径。

本系列使用的项目要求 Node.js 版本不低于 22.19.0。如果你的版本更低，先升级 Node.js，再继续后面的步骤。

第二步：安装 Git for Windows

打开 Git for Windows 官网下载安装包。安装过程中大多数选项保持默认即可。

装好之后，在开始菜单里搜索并打开 Git Bash，输入：

git --version
bash --version

能看到版本号就可以了。

为什么要装 Git Bash？因为 Pi 在 Windows 上需要 Bash 来执行工具命令。项目会按顺序寻找你配置的 Shell 、 Git Bash，以及系统路径里的 bash.exe。对第一次使用的人来说，Git Bash 的配置成本最低。

第三步：安装 Pi

在 Git Bash 里运行：

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

这里的 -g 表示全局安装，安装后可以在不同文件夹里使用 pi 命令。--ignore-scripts 会跳过依赖包的生命周期脚本，Pi 的常规 npm 安装不需要这些脚本。

安装完成后检查：

pi --version

如果能看到版本号，Pi 已经装好了。

第四步：启动第一次会话

先创建一个专门练习的文件夹。你可以在资源管理器里新建，也可以在 Git Bash 里运行：

mkdir -p ~/pi-first-test
cd ~/pi-first-test

然后启动 Pi：

pi

第一次进入时，Pi 可能会显示项目是否信任的提示。现在这个文件夹是你刚刚创建的练习目录，可以选择信任。以后遇到陌生项目，不要习惯性确认，先看清楚它会加载哪些项目配置和扩展。

如果 Pi 进入了交互界面，你会看到一个输入区域。这个界面会显示当前工作目录、模型、上下文使用量和工具调用结果。官方文档中的界面示意如下，版本升级后外观可能会变化。

先输入一条不会修改文件的请求：

请告诉我当前工作目录是什么，并列出你现在能使用的工具。不要修改任何文件。

这句话有两个作用：你能确认 Pi 是否找到了正确的目录，也能看到它对工具的基本理解。

第五步：用 DeepSeek V4 Flash 登录

如果 Pi 提示还没有可用模型，在输入区输入：

/login deepseek

Pi 会进入 DeepSeek 的登录配置流程。选择 API Key 方式，把你在 DeepSeek 控制台创建的 Key 填入。 Key 只输入到本机的登录流程里，不要贴到聊天窗口、文章截图或公共代码仓库。

Pi 当前仓库把 DeepSeek 作为内置的 OpenAI 兼容服务商，使用的环境变量名是 DEEPSEEK_API_KEY。如果你更习惯先在 Git Bash 里设置环境变量，也可以这样运行：

export DEEPSEEK_API_KEY="你的 DeepSeek API Key"
pi

Windows PowerShell 对应写法是：

$env:DEEPSEEK_API_KEY = "你的 DeepSeek API Key"
pi

这种写法只对当前终端窗口有效。关闭窗口后，变量就会消失。长期使用时，优先用 Pi 的 /login 管理凭据，或者按 DeepSeek 官方文档配置环境变量。

进入 Pi 后，输入：

/model

在模型列表里选择 DeepSeek V4 Flash。不同版本的模型目录可能会刷新，界面中的实际名称以当前列表为准。选好后再输入：

你好，请用一句话说明你是谁，再告诉我如何安全地结束这次会话。

能得到回答，就完成了第一轮闭环：你提出任务，Pi 把消息交给 DeepSeek V4 Flash，模型返回结果，Pi 再把结果显示出来。

你刚才到底完成了什么

这一轮看起来只是“安装了一个命令行工具”，实际已经接触到 Agent 的几个组成部分：

模型理解你的自然语言。
Pi维护对话和工作目录。
工具让模型可以读取文件、写入文件、修改文件或执行 Bash 命令。
会话保存过程，方便稍后继续。
项目配置决定 Pi 在当前文件夹里加载哪些规则和扩展。

下一期会专门拆开工具调用。我们会建一个只有几行内容的测试文件，让 Pi 先读取，再提出修改建议，最后由你决定是否允许它写回文件。

先记住这三个安全习惯

第一次使用 Agent，放在专门的测试文件夹里。
涉及删除、覆盖、安装和联网的命令，先看清楚再确认。
任何 API Key 、登录凭据和私人文件，都不要直接交给不清楚的数据处理路径。

Pi 的仓库地址：

https://github.com/earendil-works/pi

这一期先到这里。把安装、登录和第一次对话跑通，后面的工具、会话和扩展才有落脚点。