命令行 —— 七块零件,一条命令
前七章攒下七个入口:demo.ts、demo-memory.ts、demo-model.ts、demo-tools.ts、
demo-compact.ts、demo-session.ts、demo-hooks.ts。每个都只能演示一件事。
用户要的不是七个 demo,是一条命令。
这一章把零件装起来:选 provider、拼工具表、接会话、顺手挂压缩、最后把事件流 打到屏幕上。
三个问题:
- 参数怎么解析?手写
for还是上库? - 一条命令跑完,怎么告诉外界「成功还是失败」?
- 接上
--session以后,「续聊」到底发生了什么?
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一、本章终点:先跑起来
cd examples/mini-agentnode src/cli.ts --mock "读 README"[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 -->
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 内容。
node src/cli.ts --fixture "你好"[turn 1] 你好,这是一份录好的回复。[stop]看结构:--print 把最后四条消息原样打出来(下面重排过,原样是每字段一行)。
[ { "role": "user", "content": "hi" }, { "role": "assistant", "content": [{ "type": "text", "text": "(mock)收到:hi" }], "stopReason": "stop" }]slice(-4) 是「只看最近一段」的意思。别指望它打出完整历史——要完整就把
slice(-4) 删掉。
续聊:同一个文件跑两次。
node src/cli.ts --mock --session tmp-e08.jsonl "读 README"node src/cli.ts --mock --session tmp-e08.jsonl "再说一句"[turn 1] 先看看文件。-> read [ok][turn 2] (mock)读完了,文件已经在上下文里。[stop][turn 1] (mock)读完了,文件已经在上下文里。[stop]第二次只跑了一轮,而且直接说「读完了」——因为它从文件里读到一条 tool 消息,
mock 的规则二立刻命中(provider/mock.ts:只要历史里有 tool 结果就收尾)。
这不是会话的 bug,是 mock 太笨:它没法区分「上辈子读过」和「这一轮读过」。 真模型会看你的新问题再决定要不要再读一遍。文件本身是对的:
6 行:user > assistant > tool > assistant > user > assistant五、三个坑(都实测过)
坑一:--max-turns abc 静默成功。
node src/cli.ts --mock --max-turns abc "hi"[maxTurns]一行,零轮,退出码 0。Number("abc") 是 NaN,而 while (turns < NaN)
永远是假——循环一次都没进。CI 会绿,因为它只看退出码。
坑二:拼错的参数变成 prompt。 把 --session 打成 --sessoin:
[turn 1] (mock)收到:--sessoin tmp-x.json hifor 最后一行的 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 个测试,全绿。
自检
- 把
--session那行的argv[++i]改成argv[i + 1],会发生什么? - 第二次
--session为什么没再读文件?换成--openai会怎样? 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 五种接口。你刚亲手实现过的命令解析、 工具循环、会话落盘,在那里会变成"五个字段填什么"。