源码篇第7章 户口本上的住址——pi-coding-agent ​

小A和老Z查看记录会话原住址的户口本,金色路径通向已备好资源与模型的原项目工作间。

本章导读: 源码路线第 ⑥ 站(产品层)。进入最厚的 pi-coding-agent 包,读 main.ts、core/agent-session-services.ts 和 core/model-runtime.ts。这一站要跟着一次 pi 命令从敲下去到会话跑起来,弄清楚参数怎么解析、资源按哪个目录装配、三种模式怎么分叉。

小A昨天在项目 A 里开了个会话,今天站在项目 B 的目录下想把它恢复出来。他敲下命令,忽然停住:“老Z,这个会话当初是在 A 里建的,恢复的时候项目资源到底按哪个目录加载?按我现在的启动目录,还是按它会话自己的目录?”

“这正好是 pi-coding-agent 启动链里最容易被忽略的一个问题。”老Z说,“终端层只能显示和输入,把命令行参数、当前目录、会话、模型和交互模式装配为产品的是 pi-coding-agent。我们沿入口回答你的问题;工具、扩展和信任边界由下一章展开。”

本章源码证据均来自上游 pi 标签 v1.0.0(提交 a13d35a742c6ef8462812a28fbe1d8c8b7431c32,包版本 1.0.0,2026-10-01)。本章跟读 main() 从参数解析到模式分派的主路径,以及会话目录、服务装配和三种运行模式;不逐项覆盖包管理器、首次设置、迁移、导出 HTML、远程目录刷新和每个 CLI flag,工具、扩展与信任边界留给源码篇第8章。

入口先处理不会启动会话的命令 ​

小A猜:“main() 第一行,该是把参数解析出来吧?”

“恰恰相反,第一行就在过滤‘根本不该启动会话’的东西。”老Z打开 packages/coding-agent/src/main.ts:

ts
export async function main(args: string[], options?: MainOptions) {
  if (await runAuthCommand(args)) return;
  if (await handlePackageCommand(args, { extensionFactories })) return;
  if (await handleConfigCommand(args, { extensionFactories })) return;
  if (args[0] === "mcp") { /* 懒加载 MCP 子命令 */ return; }
  const parsed = parseArgs(args);
  if (parsed.diagnostics.some((d) => d.type === "error")) process.exit(1);
  // 建立会话和运行时
}

“逐段读,先分清‘命令已处理’与‘发生错误’:前两个是正常早退;参数 diagnostics 中有 error 才设置失败退出。版本、导出、help 和模型列表也各有早退分支,别把所有 return 解读为调用失败。”

“这些早退分支的先后顺序,有讲究吗?”

“有。”老Z说,“runAuthCommand 排在最前,连 bootstrap 设置都还没建;它处理 pi auth print-api-key、pi auth print-bearer-token 和 pi auth check,自己内部 parseArgs 一次。handlePackageCommand、handleConfigCommand 和 pi mcp 子命令也排在 parseArgs 之前,因为它们处理的是 pi install xxx、pi config set、pi mcp add 这种子命令,参数解析规则跟主命令不一样。再往后才是主参数解析、--version、--export。help 和 --list-models 比较特殊,要等 runtime 装出来才能打印:help 要列扩展 flag,list-models 要有 modelRuntime,所以那两个 process.exit(0) 在文件靠后的位置,不在这一段。”

“Windows 那个 pi update 为什么特殊处理?”

“注释里写得很清楚:Node 在 Windows 上,process.exit(0) 如果在 fetch() teardown 期间触发会 assert,所以成功的 pi update 让它自然 drain 而不强制退出。”老Z说,“这是个平台特例,别当成通用模式。注意它只在 exitCode === 0 && args[0] === "update" 时 drain;非零退出码照常 process.exit(exitCode),避免把失败误判为成功。”

cli.ts 调用 main(args)。参数诊断、--version、导出、RPC 文件参数限制、fork/session ID 校验都在会话运行时创建之前完成。把早退分支摊开看,能更快记住哪些 return 是成功、哪些是失败:

text
main() 的早退分支(v1.0.0,按执行顺序):
| 分支 | 触发条件 | 结果 |
| --- | --- | --- |
| runAuthCommand | `pi auth print-api-key`/`print-bearer-token`/`check` | 自己内部 parseArgs;check 用 0/1/2 区分就绪、未就绪、无效 |
| handlePackageCommand | `pi install`/`update`/`uninstall`… | 合并 exitCode 后退出 |
| handleConfigCommand | `pi config set`… | return |
| mcp 子命令 | `args[0] === "mcp"` | 懒加载后设 exitCode 并 return |
| 参数诊断含 error | `parseArgs` 的 diagnostics | exit(1) |
| --version | `parsed.version` | 打印 VERSION 后 exit(0) |
| --export | `parsed.export` | 导出后 exit(0) |
| RPC 带 @file 参数 | rpc 且 fileArgs 非空 | exit(1) |
| fork/session-id 冲突 | validateForkFlags / validateSessionIdFlags | exit(1) |
| help / --list-models | 要等 runtime 装完才能列 | 文件靠后 exit(0) |

“这张表里有个容易看漏的点:handlePackageCommand 退出前还要合并 process.exitCode,因为子命令内部可能已经设过退出码。”老Z说,“除了子命令自己设的退出码,主路径真正的失败信号到头来只有两类:参数诊断里的 error,以及后面 runtime 诊断里的 error。”

主调用链(节选)是:

text
cli.ts → main(args) → parseArgs()
  → createSessionManager()
  → createAgentSessionRuntime(createRuntime, ...)
  → createAgentSessionServices() → createAgentSessionFromServices()
  → InteractiveMode.run() | runPrintMode() | runRpcMode()

节选省略迁移、诊断与主题初始化。模式由 resolveAppMode(parsed, stdinIsTTY, stdoutIsTTY) 决定;非交互输出会接管 stdout,管道 stdin 在非 RPC 情况下可把交互模式改为打印模式。resolveAppMode 还会返回 "json" 这种模式,它和 "print" 走同一个打印 runner,只是输出格式由 toPrintOutputMode() 切换成 JSON。

先找会话,再确定运行时目录 ​

小A把话题拉回开场:“那目录到底在哪一步定下来?”

“看 main() 的 session 创建段。”老Z说:

ts
let sessionManager = await createSessionManager(parsed, cwd, sessionDir, startupSettingsManager);
const missingSessionCwdIssue = getMissingSessionCwdIssue(sessionManager, cwd);
if (missingSessionCwdIssue) {
  if (appMode === "interactive") { /* 询问并打开 */ }
  else { console.error(...); process.exit(1); }
}

“详细状态序列是:启动 cwd → bootstrap settings → sessionDir → SessionManager → session cwd → runtime settings/resources/models → session runtime → mode。main() 以启动目录创建临时设置管理器,用它协助确定 session directory 和创建/打开 SessionManager。随后通过 sessionManager.getCwd() 得到会话目录,再在 createRuntime 内以该目录创建运行时设置、资源和模型范围。”

比喻:户口本上的住址

会话像一个人,metadata 就是他的户口本,cwd 是登记的住址。恢复会话不是把他从口袋里掏出来,而是回到他登记的住址去办事,不跟着你现在的脚后跟走。

“所以答案是:恢复来自另一项目的会话时,项目设置、资源、Provider 注册和模型解析都不该绑定到你敲命令的那个目录,而要跟会话登记的目录走。”老Z说,“若会话缺少 cwd,交互模式调用 promptForMissingSessionCwd() 让用户选择;非交互模式输出 MissingSessionCwdError 并以失败退出。这里宁可走一条明确的错误路径,也不静默猜一个目录。”

“‘缺少 cwd’具体怎么判定?”

“看 getMissingSessionCwdIssue():它先确认有 session 文件(内存会话没有),再取 sessionManager.getCwd(),用 existsSync 判断这个目录还在不在。”老Z说,“不在就返回 issue。fallbackCwd 是当前 process.cwd()。交互模式弹个选择器,让用户在‘继续用当前 cwd’和‘取消’之间选;选完用 SessionManager.open(..., selectedCwd) 重新打开并改写 cwd。非交互模式直接拒,因为没人能选。”

“那 createSessionManager 内部那些 --session/--resume/--fork 又怎么分?”

“它是一条优先级链,按顺序短路。”老Z说:

text
createSessionManager() 的优先级链(短路求值):
  noSession / help / listModels → inMemory(不落盘)
  fork → 先查目标 id 是否已存在 → 解析路径 → forkFrom
  session → 解析路径:path/local 直接 open;
            global 打印“会话在别的项目”并询问是否 fork 进当前目录;
            not_found 报错退出
  resume → 选择器(本地列表 + 全局列表)→ open
  continue → continueRecent
  sessionId → 本项目精确或前缀匹配 → open;否则提示并新建
  兜底 → SessionManager.create

“每个分支的出口含义要分清:fork 里查目标 id 已存在是为了防止撞号,查到就退出;session 里 global 分支问‘要不要 fork 进当前目录’,选‘不’就 process.exit(0) 安静离开;resume 里选择器返回空是用户主动取消。”老Z说,“这些 exit 都是‘用户取消’或‘找不到’,不是 bug。”

“‘全局匹配’靠什么实现?”

“resolveSessionPath:参数里含 /、\ 或 .jsonl 结尾就先当文件路径 resolve;否则先用 SessionManager.findById 在本项目找精确 id,注释说明这只需读会话头;找不到再 SessionManager.list(cwd) 做前缀匹配,还找不到才 listAll 全项目扫。所以‘在别的项目找到’才进入 global 分支,项目内优先本来就是搜索顺序的一部分。”

本章其余小节为付费内容

登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。