Pi Agent 源码级教程
E08

命令行 —— 七块零件,一条命令

1,602 字 · 含 150 行代码 · 约 10 分钟

前七章攒下七个入口:demo.ts、demo-memory.ts、demo-model.ts、demo-tools.ts、 demo-compact.ts、demo-session.ts、demo-hooks.ts。每个都只能演示一件事。 用户要的不是七个 demo,是一条命令。

这一章把零件装起来:选 provider、拼工具表、接会话、顺手挂压缩、最后把事件流 打到屏幕上。

三个问题:

  1. 参数怎么解析?手写 for 还是上库?
  2. 一条命令跑完,怎么告诉外界「成功还是失败」?
  3. 接上 --session 以后,「续聊」到底发生了什么?
text
  argv --> parse --> provider / tools / session / maxTurns                          |                          v                     handle(input)                          |      remember(user) --> runAgent(--> provider --> tools)                          |            |                          |            '-- project = 压缩 + 投影                          v      result.messages.slice(len) --> remember() --> session.append()                          |                   printEvent() 打到 stdout

一、本章终点:先跑起来

bash
cd examples/mini-agentnode src/cli.ts --mock "读 README"
text
[turn 1] 先看看文件。-> read [ok][turn 2] (mock)读完了,文件已经在上下文里。[stop]

四行输出,全部来自 E01 的事件流:turn_start 打 [turn n]、 text_delta 直接写、tool_start 打 -> name、agent_end 打 [stop] 再换行。

这就是「事件驱动的回报」:换 UI 不用改循环。终端是它的第一个消费者,不是唯一一个。

文件 行数 本章变化
src/cli.ts 106 新增:参数 + 装配 + 两种模式
合计 1,252 E07 的 1,146 + 本章 106

二、106 行

<!-- file: examples/mini-agent/src/cli.ts -->

ts
import { createInterface } from "node:readline/promises";import { stdin, stdout } from "node:process";import { runAgent } from "./loop.ts";import { toLlm } from "./messages.ts";import { compactIfNeeded } from "./compact.ts";import { Session } from "./session.ts";import { baseTools, writeTool } from "./tools.ts";import { createMockProvider } from "./provider/mock.ts";import { createFixtureProvider } from "./provider/fixture.ts";import { createOpenAIProvider } from "./provider/openai.ts";import type {  AgentEvent,  AgentMessage,  Provider,  StopReason,} from "./types.ts";const argv = process.argv.slice(2);let providerName = "mock";let sessionFile = "";let prompt = "";let maxTurns = 3;let withWrite = false;let print = false;for (let i = 0; i < argv.length; i += 1) {  const arg = argv[i];  if (arg === "--mock") providerName = "mock";  else if (arg === "--fixture") providerName = "fixture";  else if (arg === "--openai") providerName = "openai";  else if (arg === "--session") sessionFile = argv[++i] ?? "";  else if (arg === "--max-turns") maxTurns = Number(argv[++i] ?? 3);  else if (arg === "--tools") withWrite = true;  else if (arg === "--print") print = true;  else prompt = [prompt, arg].filter(Boolean).join(" ");}function pickProvider(): Provider {  if (providerName === "openai") return createOpenAIProvider();  if (providerName === "fixture") {    return createFixtureProvider("fixtures/openai-basic.jsonl");  }  return createMockProvider();}const provider = pickProvider();const tools = withWrite ? [...baseTools, writeTool] : baseTools;const session = sessionFile ? Session.load(sessionFile) : null;const history: AgentMessage[] = session ? [...session.messages] : [];function remember(message: AgentMessage): void {  history.push(message);  session?.append(message);}function printEvent(event: AgentEvent): void {  if (event.type === "text_delta") stdout.write(event.text);  else if (event.type === "turn_start") {    stdout.write(`\n[turn ${event.turn}] `);  } else if (event.type === "tool_start") stdout.write(`\n-> ${event.name} `);  else if (event.type === "tool_end") {    stdout.write(event.isError ? "[err]" : "[ok]");  } else if (event.type === "agent_end") {    stdout.write(`\n[${event.stopReason}]\n`);  }}function project(all: AgentMessage[]) {  const compacted = compactIfNeeded(all, { threshold: 900, keep: 4 });  if (compacted.compacted) {    console.log(`\n[compact] ${compacted.dropped} 条 → 1 条摘要`);  }  return toLlm(compacted.messages);}async function handle(input: string): Promise<StopReason> {  const user: AgentMessage = { role: "user", content: input };  remember(user);  const result = await runAgent({    provider,    tools,    messages: history,    maxTurns,    project,    emit: printEvent,  });  const fresh = result.messages.slice(history.length);  for (const message of fresh) remember(message);  return result.stopReason;}if (prompt) {  const reason = await handle(prompt);  if (print) console.log(JSON.stringify(history.slice(-4), null, 2));  process.exitCode = reason === "error" ? 1 : 0;} else {  const rl = createInterface({ input: stdin, output: stdout });  console.log(`mini-agent · provider=${provider.name} · /exit 退出`);  for (;;) {    const line = (await rl.question("> ")).trim();    if (!line) continue;    if (line === "/exit") break;    await handle(line);  }  rl.close();}

三、五个决定

决定一:手写 for,不上库。 七个参数,for + ++i 二十行就够。 argv[++i] 是这一段的全部技巧:先自增再取值,把 --session a.json 的值吃掉, 顺带跳过它,免得它再被当一次 arg 落进 prompt。

决定二:三个 provider 都在,靠一个字符串选。 pickProvider() 是唯一知道 「有几种模型」的地方,handle() 只认 Provider 接口(E01 的孔)。 加第四个 provider,改这一个函数。

决定三:压缩挂在 project 里。 这是 E05 说过的顺序——压缩在 AgentMessage 层、投影在后面,所以 compactIfNeeded(...) 套在 toLlm(...) 里面。 threshold: 900 是给演示调的:默认 8000 在这条命令里永远不触发,[compact] 那行你就永远看不到(E05 的 threshold: 60 是同一个道理)。

决定四:remember() 双写。 内存 history 和磁盘 session 各写一份。 看起来重复,但两者职责不同:history 是这一轮的上下文,session 是下次启动的 上下文。任何一边漏了,都会出现「这轮记得、下轮失忆」或者反过来。

决定五:process.exitCode,不是 process.exit()。 exitCode 只是给进程 留一个数字,让它自己跑完、把 stdout 排空。exit() 是当场切断,管道里 (| Select-Object、| tee)最后几行经常丢——你会以为是打印逻辑写错了。


四、三组真实输出

回放模式:--fixture 不需要网络,也不看你的 prompt 内容。

bash
node src/cli.ts --fixture "你好"
text
[turn 1] 你好,这是一份录好的回复。[stop]

看结构:--print 把最后四条消息原样打出来(下面重排过,原样是每字段一行)。

text
[  { "role": "user", "content": "hi" },  {    "role": "assistant",    "content": [{ "type": "text", "text": "(mock)收到:hi" }],    "stopReason": "stop"  }]

slice(-4) 是「只看最近一段」的意思。别指望它打出完整历史——要完整就把 slice(-4) 删掉。

续聊:同一个文件跑两次。

bash
node src/cli.ts --mock --session tmp-e08.jsonl "读 README"node src/cli.ts --mock --session tmp-e08.jsonl "再说一句"
text
[turn 1] 先看看文件。-> read [ok][turn 2] (mock)读完了,文件已经在上下文里。[stop][turn 1] (mock)读完了,文件已经在上下文里。[stop]

第二次只跑了一轮,而且直接说「读完了」——因为它从文件里读到一条 tool 消息, mock 的规则二立刻命中(provider/mock.ts:只要历史里有 tool 结果就收尾)。

这不是会话的 bug,是 mock 太笨:它没法区分「上辈子读过」和「这一轮读过」。 真模型会看你的新问题再决定要不要再读一遍。文件本身是对的:

text
6 行:user > assistant > tool > assistant > user > assistant

五、三个坑(都实测过)

坑一:--max-turns abc 静默成功。

bash
node src/cli.ts --mock --max-turns abc "hi"
text
[maxTurns]

一行,零轮,退出码 0。Number("abc") 是 NaN,而 while (turns < NaN) 永远是假——循环一次都没进。CI 会绿,因为它只看退出码。

坑二:拼错的参数变成 prompt。 把 --session 打成 --sessoin:

text
[turn 1] (mock)收到:--sessoin tmp-x.json hi

for 最后一行的 else 什么 -- 都收。手写解析器的默认行为是「不认识就当输入」, 这在「随便聊两句」时很顺手,在「参数写错」时很致命。

坑三:text_delta 不换行,输出全靠别人补 \n。 [turn 1] 先看看文件。 后面能接上 -> read,是因为 tool_start 自己带了 \n;[stop] 能独占一行,是因为 agent_end 前面有 \n、后面也有。 少一个,两行就粘在一起——流式输出里,换行是最容易漏的那一半协议。


六、与 Pi 的对照(可选)

Pi 的入口只有一行:cli.ts 里 main(process.argv.slice(2))。真正的解析在 packages/coding-agent/src/cli/args.ts,480 行,parseArgs(args: string[]): Args (:72)。它比我们多的不是参数数量,是三条分类规则:

  • 已知的 --flag 各自落到 Args 的字段;
  • 不认识的 --flag 进 unknownFlags(:56),留给扩展自己认领(:249-262);
  • 以 - 开头但不认识、又不是 -- 的,压一条诊断 Unknown option: ${arg}(:264),由调用方决定是否打 usage。

注意第三条:未知参数是诊断,不是 prompt。我们的 else 分支正好相反, 这就是坑二的来源。


七、全部零件盘点

到这里 Part E 结束。examples/mini-agent/src 一共 18 个文件、1,252 行:

层 文件 行
契约 types.ts 106
消息 messages.ts 33
循环 loop.ts 98
工具 tools.ts 139
压缩 compact.ts 56
会话 session.ts 37
钩子 hooks.ts 46
入口 cli.ts 106
provider provider/mock.ts 40
provider provider/fixture.ts 42
provider provider/openai.ts 159
demo demo.ts 60
demo demo-memory.ts 92
demo demo-model.ts 40
demo demo-tools.ts 52
demo demo-compact.ts 31
demo demo-session.ts 47
demo demo-hooks.ts 68
合计 18 个文件 1,252

外加 test/ 下 5 个文件、249 行、14 个测试,全绿。

自检

  1. 把 --session 那行的 argv[++i] 改成 argv[i + 1],会发生什么?
  2. 第二次 --session 为什么没再读文件?换成 --openai 会怎样?
  3. project 里的 threshold: 900 如果改回 E05 的默认值 8000,会出现什么现象?

参考答案:

第 1 题:值照样取到,但 i 没跳过,a.json 会再被当成一次 arg,落进 prompt——于是文件续上了,用户的话里却多了一个文件名。++i 的副作用就是 「消费掉这个参数」。

第 2 题:mock 的规则二只看「历史里有没有 tool 消息」,有就直接收尾。 换成 --openai,模型看到的是完整的六条历史,会按新问题决定要不要再调工具。 同一份会话,两种 provider 的行为完全不同——这才是「接口统一、实现各异」的 正常状态。

第 3 题:[compact] 那行永远不出现。因为这条命令聊十轮也就一两千 token, 到不了 8000。演示用的阈值必须调到「必过」,否则你分不清「没触发」和「触发坏了」。


八、Part E 之后

七个零件、一万两千字,换来一个能跑、能存、能扩展、能上真实模型的 mini-agent。 它和 Pi 的差距不在行数,在下面这些地方——也就是 M 系列十篇的内容:

  • 模型调用:重试、流式增量的合并、toolCall 的多个 index(M04);
  • 工具:并发上限、超时、AbortSignal 穿透、结果截断(M05);
  • 消息:图片、thinking 块、不同 provider 的方言(M06);
  • 上下文:按模型预算算、按消息边界切、摘要用模型生成(M08/M09);
  • 会话:分支树、header 版本、跨进程锁(M10);
  • 还有 durable、chord、mcp、tui、telemetry——每一块都是「你这个洞,别人填了 一千行」。

先把这一条命令跑通,再去读他们。顺序反过来,你会以为那些代码是凭空长出来的。

还有一条路不走源码:你不需要造一个 Agent,只需要把 Pi 用好、配好、扩好。 那是 Part F 十章的事——F01 配置、F03 工具开关、F05/F06 写扩展、 F07 MCP 与 codemode、F08 打包分发、F09 五种接口。你刚亲手实现过的命令解析、 工具循环、会话落盘,在那里会变成"五个字段填什么"。