pi 系统学习手册 第 10 / 12 章 总目录 单页全本 架构图 GitHub

手册/第 10 章

10

动手练习:六个渐进任务

每个练习都能在 5–15 分钟内完成,并且刻意对应前面某一节。 建议按顺序做,因为它们从「观察」逐步走到「改造」。

1
装上并跑通一次
对应第 01 节 · 目标是确认四层结构在你机器上真的串起来了
bash
curl -fsSL https://pi.dev/install.sh | sh
# 或: npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 需要 Node.js 22.19+

pi            # 进入交互模式,用 /login 或 /model 配置模型
pi --print "用三句话说明这个仓库是做什么的"
2
拆开一次会话看结构
对应第 06 节 · 亲眼看到「树」而不是「数组」
bash
f=$(ls -t ~/.pi/agent/sessions/*/*.jsonl | head -1)
wc -l "$f"
jq -r '[.type, (.id//"-"), (.parentId//"ROOT")] | @tsv' "$f" | head -20

观察点:parentId 如何串成链、usage 与 model_change 也在其中。

3
用只读工具集做一次代码审查
对应第 05 节 ⑤ · 体验「工具集就是权限边界」
bash
pi --tools read,grep,find,ls --print "审查 packages/agent,列出三个设计风险"
# 没有 bash / write / edit,agent 物理上无法改文件
4
给 system prompt 追加约束
对应第 05 节 ④ · 体验 addendum 分节
bash
cat > /tmp/strict.md <<'EOF'
- 任何修改前,先用 read 完整读完目标文件
- 报告里必须给出 file:line 证据
EOF

pi --append-system-prompt /tmp/strict.md --print "检查 bash 工具的超时处理"
5
写第一个扩展
对应第 08 节 · 从「使用者」变成「改造者」
bash
mkdir -p ~/.pi/agent/extensions
cat > ~/.pi/agent/extensions/hello.ts <<'EOF'
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("hello", {
    description: "Show a greeting",
    handler: async (name, ctx) => {
      ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
    },
  });
}
EOF

pi --extension ~/.pi/agent/extensions/hello.ts
# 会话内输入 /hello

进阶:改成 beforeToolCall 钩子,记录每次 bash 命令,就能自己造审计日志。

6
用 SDK 嵌入十行代码
对应第 08 节 · 验证「UI 是可替换的」
typescript
import { createAgentSession } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession();
try {
  await session.prompt("列出当前目录的文件,并说明各自用途");
  console.log(session.getLastAssistantText());
} finally {
  session.dispose();
}

想做无文件会话:createAgentSession({ sessionManager: SessionManager.inMemory() })。

本章学习记录

记录仅保存在当前浏览器。