main.ts 第一阶段：特殊命令拦截

概述

main() 函数是整个程序的指挥中心。在进入复杂的 agent 流程之前，程序会先检查用户是不是在执行三个"一次性命令"。如果是，处理完直接退出，后面的解析参数、创建会话等逻辑完全跳过。

export async function main(args: string[], options?: MainOptions) {
    resetTimings();
    const extensionFactories = [...builtInExtensions, ...(options?.extensionFactories ?? [])];
    const offlineMode = args.includes("--offline") || isTruthyEnvFlag(process.env.PI_OFFLINE);
    if (offlineMode) {
        process.env.PI_OFFLINE = "1";
        process.env.PI_SKIP_VERSION_CHECK = "1";
    }

    if (await runAuthCommand(args)) {
        return;
    }

    // ... 中间代码 ...

    if (await handlePackageCommand(args, { extensionFactories })) {
        // ... 处理退出码 ...
        process.exit(exitCode);
        return;
    }

    if (await handleConfigCommand(args, { extensionFactories })) {
        return;
    }

    // ... 后续的正常 agent 流程 ...
}

拦截 1：runAuthCommand()

触发条件： 用户输入 pi auth ...

支持的命令：

pi auth check --provider openai        # 检查认证是否可用
pi auth print-api-key --provider openai # 打印 API key
pi auth print-bearer-token --provider openai-codex  # 打印 OAuth token

代码实现：

async function runAuthCommand(args: string[]): Promise<boolean> {
    if (isAuthCommandHelp(args)) {
        printAuthCommandHelp();
        return true;
    }

    let command: AuthCommand | undefined;
    try {
        command = parseAuthCommand(args);
    } catch (error) {
        const message = error instanceof AuthCommandError ? error.message : "Failed to parse auth command";
        console.error(chalk.red(`Error: ${message}`));
        process.exitCode = 1;
        return true;
    }
    if (!command) return false;

    // ... 执行认证操作 ...

    return true;
}

执行流程：

1. 检查是不是 pi auth --help，是的话打印帮助并返回 true
2. 尝试把参数解析成 auth 命令对象。如果不是 auth 命令，返回 undefined，函数返回 false，继续走后面的流程
3. 如果是 auth 命令，执行对应操作：
   • check → 检查认证状态，输出 ready/not_ready/invalid
   • 其他 → 打印凭证（API key、bearer token 等）
4. 最后返回 true，main() 里的 if 成立，直接 return 退出

check 命令的详细逻辑：

if (command.kind !== "check") {
    const signal = AbortSignal.timeout(15_000);
    const modelRuntime = await ModelRuntime.create({ allowModelNetwork: false, signal });
    const credential = await resolveCredentialForPrint(
        parsed, modelRuntime, command.kind, command.minExpiryMs, signal,
    );
    process.stdout.write(`${credential}\n`);
    return true;
}

const requestedAuth = validateAuthCommandArgs(parsed, command.kind);
let result: AuthCheckResult;
let credential: string | undefined;
try {
    const credentials = command.noRefresh ? new ReadOnlyAuthStorage() : AuthStorage.create();
    const modelRuntime = await createAuthCheckModelRuntime(credentials);
    result = await checkProviderAuth(parsed, modelRuntime, { refresh: !command.noRefresh });
    if (command.credentials && result.status === "ready") {
        credential = await getProviderCredential(result.provider, modelRuntime, credentials, {
            refresh: !command.noRefresh,
        });
        if (!credential) {
            result = { status: "not_ready", provider: result.provider, reason: "credential_not_available" };
        }
    }
} catch {
    result = {
        status: "invalid",
        provider: requestedAuth.provider ?? requestedAuth.model!,
        reason: "invalid_state",
    };
}
const output = command.json
    ? JSON.stringify({ ...result, ...(credential ? { credentials: credential } : {}) })
    : (credential ?? result.status);
process.stdout.write(`${output}\n`);
process.exitCode = result.status === "ready" ? 0 : result.status === "not_ready" ? 1 : 2;

check 命令会尝试连接 Provider，验证认证信息是否有效。支持 JSON 输出格式（--json）。

拦截 2：handlePackageCommand()

触发条件： 用户输入 pi install/remove/uninstall/update/list ...

支持的命令：

pi install @some/extension     # 安装扩展
pi update                      # 更新 pi 自身
pi update self                 # 同上
pi remove @some/extension      # 删除扩展
pi uninstall @some/extension   # 同上
pi list                        # 列出已安装的扩展

代码实现：

if (await handlePackageCommand(args, { extensionFactories })) {
    const exitCode = process.exitCode ?? 0;
    if (process.platform === "win32" && exitCode === 0 && args[0] === "update") {
        // We normally prefer process.exit(0) for package commands so bad extensions cannot keep
        // one-shot commands alive. On Windows, Node can assert after fetch() if process.exit(0)
        // runs during teardown; let successful `pi update` drain naturally instead.
        // https://github.com/nodejs/node/issues/56645
        return;
    }
    process.exit(exitCode);
    return;
}

Windows 特殊处理：

Windows 上有个 Node.js 的 bug（nodejs/node#56645），process.exit() 可能在 fetch() 还在收尾时就强制退出，导致断言错误。所以 Windows 上成功的 update 命令不调用 process.exit()，让程序自然结束。

其他情况下，执行完后调用 process.exit(exitCode) 退出，exit code 0 表示成功，非 0 表示失败。

拦截 3：handleConfigCommand()

触发条件： 用户输入 pi config

代码实现：

if (await handleConfigCommand(args, { extensionFactories })) {
    return;
}

做什么： 打开一个终端 UI（TUI），让用户通过 Tab 切换作用域，选择启用或禁用包资源（扩展、技能、提示词模板、主题）。

完成后返回，程序退出。

三个拦截的共同模式

三个拦截函数都遵循相同的模式：

if (await someCommand(args)) {
    return;  // 或 process.exit()
}

• 如果函数返回 true → 命令已处理，main() 退出
• 如果函数返回 false → 不是这个命令，继续往下走

第一阶段结束后的状态

三个拦截全部通过后（三个函数都返回 false），程序确认：用户不是在执行一次性命令，而是要进入正常的 agent 流程。

接下来进入第二阶段：正式解析参数，然后根据参数决定后续流程。