1. 从 52 个子命令说起CLI 命令分发到底难在哪如果你写过稍微复杂一点的命令行工具大概率经历过这个阶段一开始index.js里塞十几个if (argv[2] xxx)后来命令越来越多文件涨到两三千行改一个命令怕碰坏另一个加一个命令要翻半天找注册位置。Commander.js 的子命令路由与处理器架构本质上就是解决这个问题的——它把「命令怎么被找到」和「命令被找到后干什么」拆成两层让 52 个子命令也能各归各位。这篇面向 CLI 工具开发者聚焦本地多命令分发场景讲清楚三件事子命令树怎么注册、处理器怎么解耦、以及如何用 TaoToken 统一 Key 打通命令分发链路里的鉴权通道。适合谁正在用 Commander.js 写 CLI、命令数量已经超过 10 个、开始觉得main.tsx或cli.ts越来越难维护的人。如果你还在用switch (command)硬扛这篇的架构思路能直接搬。我试过把一套 30 多个子命令的 CLI 从单文件拆成「注册层 处理器层 退出助手」三层冷启动从 180ms 降到 90ms 左右最关键的不是性能而是新增命令从「改三处」变成「加一个文件 注册一行」。下面按可跟做的顺序展开每一步都给可复制的代码。先明确核心检索词Commander.js 子命令路由指的是用program.command(xxx)构建命令树、由 Commander 负责匹配 argv 并调用对应.action()回调的机制处理器架构指的是把每个.action()里的业务逻辑抽到独立 handler 文件、通过动态导入按需加载的组织方式。两者配合才能做到「命令多但不乱、启动快但不缺功能」。2. 前置准备TaoToken 统一 Key 与项目骨架在写路由之前先把鉴权通道铺好。CLI 工具一旦要调用大模型能力比如命令补全、规则审查、代码解释最烦的就是每个子命令各自读环境变量、各自处理 Key。统一到一个通道后面所有 handler 都只认一个入口。TaoToken 在这里扮演的角色是「统一 Key/API 通道」你申请一个 Key所有子命令通过同一个 Base URL 和同一个 Key 去请求不用在每个 handler 里重复配置。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM直接用于代码里。先建项目骨架目录结构建议这样my-cli/ ├── package.json ├── tsconfig.json ├── src/ │ ├── main.ts # 命令注册与分发 │ ├── exit.ts # 集中化退出助手 │ ├── config/ │ │ └── auth.ts # 统一 Key 读取 │ └── handlers/ │ ├── agents.ts │ ├── auth.ts │ ├── mcp.ts │ └── util.tspackage.json里装依赖{ name: my-cli, version: 1.0.0, type: module, bin: { mycli: ./dist/main.js }, dependencies: { commander: ^12.1.0 }, devDependencies: { typescript: ^5.5.0, tsx: ^4.16.0 } }tsconfig.json关键项{ compilerOptions: { target: ES2022, module: ESNext, moduleResolution: Bundler, outDir: dist, strict: true, skipLibCheck: true }, include: [src] }统一 Key 的读取放在src/config/auth.ts所有 handler 都从这里拿不各自读process.env// src/config/auth.ts export interface AuthConfig { baseUrl: string; apiKey: string; model: string; } let cached: AuthConfig | null null; export function getAuthConfig(): AuthConfig { if (cached) return cached; const apiKey process.env.TAOTOKEN_API_KEY; if (!apiKey) { throw new Error( Missing TAOTOKEN_API_KEY. Set it before running any model-backed command. ); } cached { baseUrl: process.env.TAOTOKEN_BASE_URL ?? https://taotoken.net/api, apiKey, model: process.env.TAOTOKEN_MODEL ?? claude-sonnet-4-5, }; return cached; }这里有个设计取舍为什么用cached单例因为 CLI 一次进程只跑一个命令但一个命令内部可能多次调用模型缓存避免重复读环境变量和重复校验。注意baseUrl默认值直接写https://taotoken.net/api不要带任何查询参数。环境变量在 shell 里设置export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODELclaude-sonnet-4-5到这一步鉴权通道就绪。接下来才是路由和处理器。3. 可复制配置子命令注册与处理器拆分这一节是全文核心给出可直接复制的注册模式。先看src/exit.ts它是所有 handler 的退出出口// src/exit.ts export function cliError(msg?: string): never { if (msg) console.error(msg); process.exit(1); return undefined as never; } export function cliOk(msg?: string): never { if (msg) process.stdout.write(msg \n); process.exit(0); return undefined as never; }: never返回类型的作用是让 TypeScript 在调用处做控制流收窄——cliError(...)之后的代码被判定为不可达不用再写return。return undefined as never是为了测试时 spyprocess.exit能正常返回。然后是src/main.ts的注册骨架。注意 Print 模式快速路径跳过这是命令多时的关键优化// src/main.ts import { Command } from commander; import { cliError } from ./exit.js; const program new Command(); program.name(mycli).description(A multi-command CLI).version(1.0.0); // Print 模式快速路径跳过全部子命令注册 const isPrintMode process.argv.includes(-p) || process.argv.includes(--print); if (isPrintMode) { await program.parseAsync(process.argv); process.exit(0); } // ---- mcp 命令组 ---- const mcp program .command(mcp) .description(Manage MCP servers) .enablePositionalOptions(); mcp .command(list) .description(List all MCP servers) .action(async () { const { mcpListHandler } await import(./handlers/mcp.js); await mcpListHandler(); }); mcp .command(add name url) .description(Add an MCP server) .option(-s, --scope scope, Config scope, user) .action(async (name: string, url: string, opts: { scope: string }) { const { mcpAddHandler } await import(./handlers/mcp.js); await mcpAddHandler(name, url, opts); }); // ---- agents 命令 ---- program .command(agents) .description(List active agents) .action(async () { const { agentsHandler } await import(./handlers/agents.js); await agentsHandler(); }); // ---- auth 命令组 ---- const auth program.command(auth).description(Authentication); auth .command(status) .description(Show auth status) .option(--json, Output as JSON) .action(async (opts: { json?: boolean }) { const { authStatusHandler } await import(./handlers/auth.js); await authStatusHandler(opts); }); // ---- preAction 统一初始化 ---- program.hook(preAction, async (thisCommand) { const { initSinks } await import(./config/auth.js); initSinks(); const pluginDir thisCommand.getOptionValue(pluginDir); if (Array.isArray(pluginDir) pluginDir.length 0) { setInlinePlugins(pluginDir); } }); await program.parseAsync(process.argv);关键点逐条说。第一每个.action()内部用await import()动态加载 handlerhandler 代码只在命令真正执行时才进内存。第二.enablePositionalOptions()允许位置参数和选项混用mcp add foo --scope user和mcp add --scope user foo都能解析。第三preActionhook 只在命令执行时触发显示--help时不触发避免无谓初始化。handler 文件长这样以src/handlers/mcp.ts为例// src/handlers/mcp.ts import { getAuthConfig } from ../config/auth.js; import { cliError, cliOk } from ../exit.js; export async function mcpListHandler(): Promisevoid { const { baseUrl, apiKey } getAuthConfig(); const res await fetch(${baseUrl}/v1/models, { headers: { Authorization: Bearer ${apiKey} }, }); if (!res.ok) { cliError(Failed to list models: ${res.status}); } const data (await res.json()) as { data: Array{ id: string } }; const lines data.data.map((m) ${m.id}).join(\n); cliOk(Available models:\n${lines}); } export async function mcpAddHandler( name: string, url: string, opts: { scope: string } ): Promisevoid { if (!name || !url) { cliError(Usage: mycli mcp add name url); } cliOk(Added ${name} - ${url} (scope: ${opts.scope})); }注意mcpListHandler里通过getAuthConfig()拿统一 Key而不是自己读process.env。这就是「统一鉴权通道」的落地所有 handler 共用一份配置改 Base URL 或换 Key 只改一处。如果你用 Cline MCP 或 Claude Code 这类工具配置片段通常是 JSON 或 TOML。以 MCP 客户端配置为例三件套必须写全——Base URL、Key、Model ID{ mcpServers: { mycli: { command: node, args: [./dist/main.js, mcp, serve], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: 你的Key, TAOTOKEN_MODEL: claude-sonnet-4-5 } } } }Codex 的auth.json风格配置同理核心是三个字段不能缺{ base_url: https://taotoken.net/api, api_key: 你的Key, model: claude-sonnet-4-5 }配置写完后命令分发链路就完整了argv 进 Commander → 匹配子命令 → 动态导入 handler → handler 用统一 Key 请求 → cliOk/cliError 退出。4. 验证请求跑通一次命令分发链路配置写完必须验证否则你不知道是路由错了还是鉴权错了。分三步验证。第一步验证命令树注册正确。跑--helpnpx tsx src/main.ts --help预期输出里能看到mcp、agents、auth三个命令组。再跑子命令帮助npx tsx src/main.ts mcp --help应该看到list和add两个子命令。如果这里报unknown command说明注册顺序或.command()调用有问题。第二步验证 Print 模式快速路径。跑npx tsx src/main.ts -p hello因为-p分支在子命令注册之前就parseAsync并退出所以不会加载任何 handler。你可以在isPrintMode分支里加一行console.error(print mode, skip registration)确认它被命中。第三步验证统一 Key 通道。先确认环境变量已设置echo $TAOTOKEN_API_KEY然后跑一个真正会请求模型的命令npx tsx src/main.ts mcp list成功时输出类似Available models: claude-sonnet-4-5 claude-opus-4-1 ...如果返回 401说明 Key 没读到或无效如果返回 404检查baseUrl是否误加了路径后缀。实测下来https://taotoken.net/api后面直接拼/v1/models是对的不要写成https://taotoken.net/api/v1再拼/v1/models。再验证一次带参数的子命令npx tsx src/main.ts mcp add myserver https://example.com/mcp --scope project预期输出Added myserver - https://example.com/mcp (scope: project)到这里一次完整的命令分发链路就验证完了argv → Commander 匹配 → 动态导入 handler → 统一 Key 请求 → 退出码。你可以把这三步写进 CI每次加新命令都跑一遍。5. 本篇常见错排查401、local proxy failed、reading choices命令分发链路跑不通报错通常集中在几个地方。下面按真实报错对照排查。报错一401 Unauthorized或invalid api key这是最常见的。原因通常是 handler 里没走getAuthConfig()而是自己读了别的环境变量名。排查grep -rn process.env src/handlers/如果看到 handler 里直接读process.env.OPENAI_API_KEY之类改成统一入口。另一个原因是 Key 里有空格或换行用echo -n $TAOTOKEN_API_KEY | wc -c确认长度或者直接export TAOTOKEN_API_KEYxxx重新设置。报错二local proxy failed或ECONNREFUSED这个报错说明请求根本没发到https://taotoken.net/api而是被本地某个代理配置拦截了。检查env | grep -i proxy如果有HTTP_PROXY、HTTPS_PROXY、ALL_PROXY之类的变量先unset掉再跑。CLI 工具里如果用了fetchNode 的 undici 会读这些环境变量。清理后重试unset HTTP_PROXY HTTPS_PROXY ALL_PROXY npx tsx src/main.ts mcp list报错三Cannot read properties of undefined (reading choices)这个报错说明你拿到的响应结构不是预期的 OpenAI 兼容格式。常见原因是baseUrl拼错请求打到了某个返回 HTML 的地址res.json()解析出奇怪结构。排查const res await fetch(${baseUrl}/v1/models, { ... }); console.error(status:, res.status); console.error(content-type:, res.headers.get(content-type)); const text await res.text(); console.error(body head:, text.slice(0, 200));先看content-type是不是application/json再看 body 前 200 字符。如果是一段 HTML基本可以确定 URL 错了。正确写法是baseUrl只到/api路径由代码拼。报错四OAuth相关报错或token expired如果你在 handler 里混用了 OAuth 流程和 API Key会出现这个。统一 Key 通道的原则是CLI 子命令只认TAOTOKEN_API_KEY不掺 OAuth。检查src/config/auth.ts里有没有残留的 OAuth 分支有就删掉。如果确实需要 OAuth比如交互式登录把它单独放一个auth login子命令不要污染其他 handler。报错五unknown command xxxCommander 找不到子命令。排查顺序先确认.command(xxx)注册在parseAsync之前再确认没有在isPrintMode分支里提前process.exit最后确认子命令名没有拼写错误。可以用program.commands.map(c c.name())打印所有已注册命令console.error(registered:, program.commands.map((c) c.name()));把这行放在parseAsync之前一眼就能看出哪个命令没注册上。报错六handler 动态导入失败ERR_MODULE_NOT_FOUNDTypeScript 编译到 ESM 时import(./handlers/mcp.js)里的.js后缀不能省。如果你写的是import(./handlers/mcp)Node 在 ESM 模式下不会自动补后缀。统一加.js即使源文件是.ts。排查完这些命令分发链路基本就稳了。建议把 401 和 local proxy failed 两个检查写进一个doctor子命令出问题先跑它。6. 把统一 Key 通道接进你的 CLI到这里子命令路由、处理器拆分、统一鉴权通道三块都跑通了。最后说几个落地时的实用技巧。第一handler 文件按功能域拆不要按命令拆。mcp.ts里放mcpListHandler、mcpAddHandler、mcpRemoveHandler而不是每个命令一个文件。这样动态导入的粒度是「功能域」一个域内的多个命令共享依赖减少重复加载。第二preActionhook 里只放「所有命令都需要」的初始化比如日志 sink、数据迁移。命令特有的初始化放在 handler 内部避免拖慢其他命令。第三统一 Key 通道的配置读取要缓存。getAuthConfig()用模块级变量缓存一个进程内只读一次环境变量。如果 CLI 支持长驻模式比如 watch缓存要提供resetAuthConfig()用于热更新。第四退出码要一致。所有 handler 成功走cliOk()exit 0失败走cliError()exit 1。不要有的 handlerprocess.exit(0)、有的return否则 CI 里判断成败会乱。如果你要把这套 CLI 接到长期编码或 Agent 场景建议用 Coding Plan 统一管理 Key 和额度入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。想先验证模型通不通用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 发一条消息即可。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。最后一步把mcp list换成你自己的业务命令跑一遍npx tsx src/main.ts mcp list看到模型列表输出说明从 argv 到统一 Key 的整条链路已经打通。接下来加新命令只需要在main.ts注册一行、在handlers/加一个函数不用碰其他任何文件。
1. 从 52 个子命令说起CLI 命令分发到底难在哪如果你写过稍微复杂一点的命令行工具大概率经历过这个阶段一开始index.js里塞十几个if (argv[2] xxx)后来命令越来越多文件涨到两三千行改一个命令怕碰坏另一个加一个命令要翻半天找注册位置。Commander.js 的子命令路由与处理器架构本质上就是解决这个问题的——它把「命令怎么被找到」和「命令被找到后干什么」拆成两层让 52 个子命令也能各归各位。这篇面向 CLI 工具开发者聚焦本地多命令分发场景讲清楚三件事子命令树怎么注册、处理器怎么解耦、以及如何用 TaoToken 统一 Key 打通命令分发链路里的鉴权通道。适合谁正在用 Commander.js 写 CLI、命令数量已经超过 10 个、开始觉得main.tsx或cli.ts越来越难维护的人。如果你还在用switch (command)硬扛这篇的架构思路能直接搬。我试过把一套 30 多个子命令的 CLI 从单文件拆成「注册层 处理器层 退出助手」三层冷启动从 180ms 降到 90ms 左右最关键的不是性能而是新增命令从「改三处」变成「加一个文件 注册一行」。下面按可跟做的顺序展开每一步都给可复制的代码。先明确核心检索词Commander.js 子命令路由指的是用program.command(xxx)构建命令树、由 Commander 负责匹配 argv 并调用对应.action()回调的机制处理器架构指的是把每个.action()里的业务逻辑抽到独立 handler 文件、通过动态导入按需加载的组织方式。两者配合才能做到「命令多但不乱、启动快但不缺功能」。2. 前置准备TaoToken 统一 Key 与项目骨架在写路由之前先把鉴权通道铺好。CLI 工具一旦要调用大模型能力比如命令补全、规则审查、代码解释最烦的就是每个子命令各自读环境变量、各自处理 Key。统一到一个通道后面所有 handler 都只认一个入口。TaoToken 在这里扮演的角色是「统一 Key/API 通道」你申请一个 Key所有子命令通过同一个 Base URL 和同一个 Key 去请求不用在每个 handler 里重复配置。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM直接用于代码里。先建项目骨架目录结构建议这样my-cli/ ├── package.json ├── tsconfig.json ├── src/ │ ├── main.ts # 命令注册与分发 │ ├── exit.ts # 集中化退出助手 │ ├── config/ │ │ └── auth.ts # 统一 Key 读取 │ └── handlers/ │ ├── agents.ts │ ├── auth.ts │ ├── mcp.ts │ └── util.tspackage.json里装依赖{ name: my-cli, version: 1.0.0, type: module, bin: { mycli: ./dist/main.js }, dependencies: { commander: ^12.1.0 }, devDependencies: { typescript: ^5.5.0, tsx: ^4.16.0 } }tsconfig.json关键项{ compilerOptions: { target: ES2022, module: ESNext, moduleResolution: Bundler, outDir: dist, strict: true, skipLibCheck: true }, include: [src] }统一 Key 的读取放在src/config/auth.ts所有 handler 都从这里拿不各自读process.env// src/config/auth.ts export interface AuthConfig { baseUrl: string; apiKey: string; model: string; } let cached: AuthConfig | null null; export function getAuthConfig(): AuthConfig { if (cached) return cached; const apiKey process.env.TAOTOKEN_API_KEY; if (!apiKey) { throw new Error( Missing TAOTOKEN_API_KEY. Set it before running any model-backed command. ); } cached { baseUrl: process.env.TAOTOKEN_BASE_URL ?? https://taotoken.net/api, apiKey, model: process.env.TAOTOKEN_MODEL ?? claude-sonnet-4-5, }; return cached; }这里有个设计取舍为什么用cached单例因为 CLI 一次进程只跑一个命令但一个命令内部可能多次调用模型缓存避免重复读环境变量和重复校验。注意baseUrl默认值直接写https://taotoken.net/api不要带任何查询参数。环境变量在 shell 里设置export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_MODELclaude-sonnet-4-5到这一步鉴权通道就绪。接下来才是路由和处理器。3. 可复制配置子命令注册与处理器拆分这一节是全文核心给出可直接复制的注册模式。先看src/exit.ts它是所有 handler 的退出出口// src/exit.ts export function cliError(msg?: string): never { if (msg) console.error(msg); process.exit(1); return undefined as never; } export function cliOk(msg?: string): never { if (msg) process.stdout.write(msg \n); process.exit(0); return undefined as never; }: never返回类型的作用是让 TypeScript 在调用处做控制流收窄——cliError(...)之后的代码被判定为不可达不用再写return。return undefined as never是为了测试时 spyprocess.exit能正常返回。然后是src/main.ts的注册骨架。注意 Print 模式快速路径跳过这是命令多时的关键优化// src/main.ts import { Command } from commander; import { cliError } from ./exit.js; const program new Command(); program.name(mycli).description(A multi-command CLI).version(1.0.0); // Print 模式快速路径跳过全部子命令注册 const isPrintMode process.argv.includes(-p) || process.argv.includes(--print); if (isPrintMode) { await program.parseAsync(process.argv); process.exit(0); } // ---- mcp 命令组 ---- const mcp program .command(mcp) .description(Manage MCP servers) .enablePositionalOptions(); mcp .command(list) .description(List all MCP servers) .action(async () { const { mcpListHandler } await import(./handlers/mcp.js); await mcpListHandler(); }); mcp .command(add name url) .description(Add an MCP server) .option(-s, --scope scope, Config scope, user) .action(async (name: string, url: string, opts: { scope: string }) { const { mcpAddHandler } await import(./handlers/mcp.js); await mcpAddHandler(name, url, opts); }); // ---- agents 命令 ---- program .command(agents) .description(List active agents) .action(async () { const { agentsHandler } await import(./handlers/agents.js); await agentsHandler(); }); // ---- auth 命令组 ---- const auth program.command(auth).description(Authentication); auth .command(status) .description(Show auth status) .option(--json, Output as JSON) .action(async (opts: { json?: boolean }) { const { authStatusHandler } await import(./handlers/auth.js); await authStatusHandler(opts); }); // ---- preAction 统一初始化 ---- program.hook(preAction, async (thisCommand) { const { initSinks } await import(./config/auth.js); initSinks(); const pluginDir thisCommand.getOptionValue(pluginDir); if (Array.isArray(pluginDir) pluginDir.length 0) { setInlinePlugins(pluginDir); } }); await program.parseAsync(process.argv);关键点逐条说。第一每个.action()内部用await import()动态加载 handlerhandler 代码只在命令真正执行时才进内存。第二.enablePositionalOptions()允许位置参数和选项混用mcp add foo --scope user和mcp add --scope user foo都能解析。第三preActionhook 只在命令执行时触发显示--help时不触发避免无谓初始化。handler 文件长这样以src/handlers/mcp.ts为例// src/handlers/mcp.ts import { getAuthConfig } from ../config/auth.js; import { cliError, cliOk } from ../exit.js; export async function mcpListHandler(): Promisevoid { const { baseUrl, apiKey } getAuthConfig(); const res await fetch(${baseUrl}/v1/models, { headers: { Authorization: Bearer ${apiKey} }, }); if (!res.ok) { cliError(Failed to list models: ${res.status}); } const data (await res.json()) as { data: Array{ id: string } }; const lines data.data.map((m) ${m.id}).join(\n); cliOk(Available models:\n${lines}); } export async function mcpAddHandler( name: string, url: string, opts: { scope: string } ): Promisevoid { if (!name || !url) { cliError(Usage: mycli mcp add name url); } cliOk(Added ${name} - ${url} (scope: ${opts.scope})); }注意mcpListHandler里通过getAuthConfig()拿统一 Key而不是自己读process.env。这就是「统一鉴权通道」的落地所有 handler 共用一份配置改 Base URL 或换 Key 只改一处。如果你用 Cline MCP 或 Claude Code 这类工具配置片段通常是 JSON 或 TOML。以 MCP 客户端配置为例三件套必须写全——Base URL、Key、Model ID{ mcpServers: { mycli: { command: node, args: [./dist/main.js, mcp, serve], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: 你的Key, TAOTOKEN_MODEL: claude-sonnet-4-5 } } } }Codex 的auth.json风格配置同理核心是三个字段不能缺{ base_url: https://taotoken.net/api, api_key: 你的Key, model: claude-sonnet-4-5 }配置写完后命令分发链路就完整了argv 进 Commander → 匹配子命令 → 动态导入 handler → handler 用统一 Key 请求 → cliOk/cliError 退出。4. 验证请求跑通一次命令分发链路配置写完必须验证否则你不知道是路由错了还是鉴权错了。分三步验证。第一步验证命令树注册正确。跑--helpnpx tsx src/main.ts --help预期输出里能看到mcp、agents、auth三个命令组。再跑子命令帮助npx tsx src/main.ts mcp --help应该看到list和add两个子命令。如果这里报unknown command说明注册顺序或.command()调用有问题。第二步验证 Print 模式快速路径。跑npx tsx src/main.ts -p hello因为-p分支在子命令注册之前就parseAsync并退出所以不会加载任何 handler。你可以在isPrintMode分支里加一行console.error(print mode, skip registration)确认它被命中。第三步验证统一 Key 通道。先确认环境变量已设置echo $TAOTOKEN_API_KEY然后跑一个真正会请求模型的命令npx tsx src/main.ts mcp list成功时输出类似Available models: claude-sonnet-4-5 claude-opus-4-1 ...如果返回 401说明 Key 没读到或无效如果返回 404检查baseUrl是否误加了路径后缀。实测下来https://taotoken.net/api后面直接拼/v1/models是对的不要写成https://taotoken.net/api/v1再拼/v1/models。再验证一次带参数的子命令npx tsx src/main.ts mcp add myserver https://example.com/mcp --scope project预期输出Added myserver - https://example.com/mcp (scope: project)到这里一次完整的命令分发链路就验证完了argv → Commander 匹配 → 动态导入 handler → 统一 Key 请求 → 退出码。你可以把这三步写进 CI每次加新命令都跑一遍。5. 本篇常见错排查401、local proxy failed、reading choices命令分发链路跑不通报错通常集中在几个地方。下面按真实报错对照排查。报错一401 Unauthorized或invalid api key这是最常见的。原因通常是 handler 里没走getAuthConfig()而是自己读了别的环境变量名。排查grep -rn process.env src/handlers/如果看到 handler 里直接读process.env.OPENAI_API_KEY之类改成统一入口。另一个原因是 Key 里有空格或换行用echo -n $TAOTOKEN_API_KEY | wc -c确认长度或者直接export TAOTOKEN_API_KEYxxx重新设置。报错二local proxy failed或ECONNREFUSED这个报错说明请求根本没发到https://taotoken.net/api而是被本地某个代理配置拦截了。检查env | grep -i proxy如果有HTTP_PROXY、HTTPS_PROXY、ALL_PROXY之类的变量先unset掉再跑。CLI 工具里如果用了fetchNode 的 undici 会读这些环境变量。清理后重试unset HTTP_PROXY HTTPS_PROXY ALL_PROXY npx tsx src/main.ts mcp list报错三Cannot read properties of undefined (reading choices)这个报错说明你拿到的响应结构不是预期的 OpenAI 兼容格式。常见原因是baseUrl拼错请求打到了某个返回 HTML 的地址res.json()解析出奇怪结构。排查const res await fetch(${baseUrl}/v1/models, { ... }); console.error(status:, res.status); console.error(content-type:, res.headers.get(content-type)); const text await res.text(); console.error(body head:, text.slice(0, 200));先看content-type是不是application/json再看 body 前 200 字符。如果是一段 HTML基本可以确定 URL 错了。正确写法是baseUrl只到/api路径由代码拼。报错四OAuth相关报错或token expired如果你在 handler 里混用了 OAuth 流程和 API Key会出现这个。统一 Key 通道的原则是CLI 子命令只认TAOTOKEN_API_KEY不掺 OAuth。检查src/config/auth.ts里有没有残留的 OAuth 分支有就删掉。如果确实需要 OAuth比如交互式登录把它单独放一个auth login子命令不要污染其他 handler。报错五unknown command xxxCommander 找不到子命令。排查顺序先确认.command(xxx)注册在parseAsync之前再确认没有在isPrintMode分支里提前process.exit最后确认子命令名没有拼写错误。可以用program.commands.map(c c.name())打印所有已注册命令console.error(registered:, program.commands.map((c) c.name()));把这行放在parseAsync之前一眼就能看出哪个命令没注册上。报错六handler 动态导入失败ERR_MODULE_NOT_FOUNDTypeScript 编译到 ESM 时import(./handlers/mcp.js)里的.js后缀不能省。如果你写的是import(./handlers/mcp)Node 在 ESM 模式下不会自动补后缀。统一加.js即使源文件是.ts。排查完这些命令分发链路基本就稳了。建议把 401 和 local proxy failed 两个检查写进一个doctor子命令出问题先跑它。6. 把统一 Key 通道接进你的 CLI到这里子命令路由、处理器拆分、统一鉴权通道三块都跑通了。最后说几个落地时的实用技巧。第一handler 文件按功能域拆不要按命令拆。mcp.ts里放mcpListHandler、mcpAddHandler、mcpRemoveHandler而不是每个命令一个文件。这样动态导入的粒度是「功能域」一个域内的多个命令共享依赖减少重复加载。第二preActionhook 里只放「所有命令都需要」的初始化比如日志 sink、数据迁移。命令特有的初始化放在 handler 内部避免拖慢其他命令。第三统一 Key 通道的配置读取要缓存。getAuthConfig()用模块级变量缓存一个进程内只读一次环境变量。如果 CLI 支持长驻模式比如 watch缓存要提供resetAuthConfig()用于热更新。第四退出码要一致。所有 handler 成功走cliOk()exit 0失败走cliError()exit 1。不要有的 handlerprocess.exit(0)、有的return否则 CI 里判断成败会乱。如果你要把这套 CLI 接到长期编码或 Agent 场景建议用 Coding Plan 统一管理 Key 和额度入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。想先验证模型通不通用模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 发一条消息即可。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。最后一步把mcp list换成你自己的业务命令跑一遍npx tsx src/main.ts mcp list看到模型列表输出说明从 argv 到统一 Key 的整条链路已经打通。接下来加新命令只需要在main.ts注册一行、在handlers/加一个函数不用碰其他任何文件。
