01 · 快速开始

从零到跑通第一个 agent，约 5 分钟：起开发服务器、指向一个 examples 源、发一条消息看到流式回复与工具调用。

前置依赖

没装过 pi？先 npm i -g @earendil-works/pi-coding-agent（或参考其文档），运行 pi 登录一次。

安装与启动（开发模式）

pnpm install
pnpm dev          # dev-all：Vite 前端 http://localhost:5173（/api 自动代理到 :3000）

**打开浏览器访问 http://localhost:5173**（不是 3000）。

为什么是两个进程、要开哪个端口

pnpm dev 实际执行 node scripts/dev-all.mjs（package.json:17），它并发拉起两个进程，任一退出或 Ctrl-C 时一起收尾（scripts/dev-all.mjs:32-36）：

开发期你面对的入口是 Vite 的 5173（有热更新、提供 SPA）；3000 是被代理的裸 API 宿主，直接打开只会看到 API 而非聊天界面。生产模式则相反——pnpm build 后 pnpm start（= node dist/server.mjs）是单进程单端口，同一个 :3000（或 PORT）既服务 SPA 静态资源又服务 /api（server/index.ts:94-104）。

打开 5173 后，在 agent source 选择器里录入一个源，三种形态：

• 含 index.ts 的目录 → 跑你的自定义 agent（custom 模式）；
• 任意目录 → 通用 CLI 模式（pi --mode rpc）；
• git 源 → 解析后同上。

只想双击运行、不想开终端？pi-web 还有一个 Tauri 桌面壳（desktop/），它内部同样 spawn dist/server.mjs 后端。详见 20 桌面版（Tauri）。

从 examples/ 选一个上手

仓库 examples/ 内置了多个可直接指向的示例（约 28 个，按能力分类整理在 examples 总索引）。第一次跑通，推荐从下面两个入门示例任选其一：

5 分钟跑通示例 agent

下面以最小例子 examples/hello-agent 为例（examples/hello-agent/index.ts）：

import { defineAgent } from "@blksails/pi-web-agent-kit";
import { defineTool } from "@earendil-works/pi-coding-agent";
import { Type } from "@earendil-works/pi-ai";
 
const echo = defineTool({
  name: "echo",
  label: "Echo",
  description: "Echo the provided text back to the caller.",
  parameters: Type.Object({
    text: Type.String({ description: "Text to echo back." }),
  }),
  async execute(_toolCallId, params) {
    return { content: [{ type: "text", text: params.text }], details: undefined };
  },
});
 
export default defineAgent({
  // model 省略 → 继承 ~/.pi/agent/settings.json 的默认 provider/model
  systemPrompt: "You are hello-agent, a minimal pi-web example agent.",
  customTools: [echo],
  // 自包含：不拉系统内置工具，也不加载磁盘发现的 skills
  noTools: "builtin",
  skills: ({ diagnostics }) => ({ skills: [], diagnostics }),
});

noTools: "builtin" 与 skills 覆盖钩子的含义见 08 自定义 Agent 开发。

步骤（每步可独立验证）：

1. pnpm dev 启动后，浏览器打开 http://localhost:5173 → 预期看到选源页。
2. 在选择器里填入 examples/hello-agent 的绝对路径（选择器需要绝对路径；或配 PI_WEB_DEFAULT_SOURCE，见下）→ 预期进入会话界面。
3. 发一句话 → 预期看到流式回复逐字出现。
4. 让它调工具：发「用 echo 工具回显 hello」（或类似指令）→ 预期会话里出现 echo 的工具卡。

没看到回复 / 报鉴权错？ 多半是默认 provider/model 无有效 key。先用下方「离线快速验证」的 stub agent 跑通链路，鉴权问题见 23 故障排查 / FAQ。

hello-agent 故意省略 model，让它继承你 pi 登录的默认 provider/model，开箱即用。要钉死模型，加 model: { provider, modelId }，但该 provider 必须有有效鉴权。

配置（可选）

凭据和默认值默认来自 ~/.pi/agent（已登录 pi 则无需任何环境 key）。要覆盖，复制 .env.local.example 为 .env.local。最常用：

# .env.local
PI_WEB_DEFAULT_SOURCE=/abs/path/to/examples/hello-agent  # 选择器默认源
PI_WEB_DEFAULT_CWD=/abs/path/to/workdir                  # 会话默认工作目录
PI_WEB_DEFAULT_PROVIDER=openrouter                       # 强制 provider（否则看 settings.json）
PI_WEB_DEFAULT_MODEL=anthropic/claude-sonnet-4.6         # 强制 model（值与 provider 对应）

完整变量见 06 配置参考。

离线快速验证（不消耗模型额度）

无 LLM key 也能验证全链路（用确定性 stub agent）。同样在 5173 打开：

PI_WEB_STUB_AGENT=1 pnpm dev
# 或跑离线 Node 级流式 e2e（无需浏览器）：
pnpm e2e:node

常用脚本速查

常见首次问题

• 打开 3000 看到裸 API / JSON？ 开发期应访问 5173（Vite 提供 SPA）；3000 是被 Vite 代理的后端宿主，不直接提供前端页面。
• 改了注入路由 / 配置域后没生效 — handler 单例 pin 在 globalThis，热重载不刷新新装配的路由，需重启 pnpm dev。
• 更多见 23 故障排查 / FAQ。

下一步

• 理解载入与会话机制 → 02 核心概念
• 写自己的 agent → 08 自定义 Agent 开发
• 接入自定义模型网关 → 07 Provider 与模型
• 打包成桌面应用 → 20 桌面版（Tauri）