企业官网建设流程全解析

1. 为什么 TuiThreadCmd 的类型总在 handler 里“断片”

如果你在 OpenCode Agent 里写过自定义命令，大概率遇到过这种场景：builder里明明声明了--thread-id是 string，到了handler里argv.threadId却变成unknown，或者argv["--"]直接报“属性不存在”。这不是你写错了，而是 yargs 的CommandModule<T, U>泛型在“命令参数类型”和“全局 argv 类型”之间留了一道缝。

TuiThreadCmd 是 OpenCode Agent 里承载 TUI 线程命令的结构化类型，它要同时表达三件事：命令名与别名、builder 阶段注入的选项、handler 阶段消费的 argv 形状。TypeScript 的结构化类型（Structural Typing）让对象字面量可以直接满足接口，但前提是你得把WithDoubleDash<U>这类类型变换显式嵌进签名里，否则编译器不会自动帮你补"--"属性。

这篇面向 TypeScript 开发者，从类型定义骨架讲到 settings.json 配置，再到本地跑通类型检查与调用链路。适合已经能写 yargs 命令、但被泛型推导卡住的人。下面所有代码都可以直接复制到你的 OpenCode Agent 项目里验证。

2. TaoToken 前置：把模型调用接进类型验证链路

TuiThreadCmd 的类型检查是纯编译期的事，但 OpenCode Agent 真正跑起来时，handler 里往往要调模型。我习惯把模型调用统一走 TaoToken 的 API，这样本地验证命令链路时不用切换多套凭证。

TaoToken 的接入点很清晰：官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 根地址是 https://taotoken.net/api 。你需要先在控制台创建 API Key，地址是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。拿到 Key 之后，模型对话调试可以用 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite ，长期编码或 Agent 场景建议看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。

注意：API Key 只放在本地环境变量或 settings.json 的 env 字段里，不要提交到仓库。TuiThreadCmd 的类型定义里也不应该出现任何密钥字面量。

接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，ClaudeCodeAnthropic 相关配置参考 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude-code-anthropic&utm_campaign=rewrite 。这些链接在后面的验证步骤里会用到。

3. 可复制配置：TuiThreadCmd 类型骨架与 settings.json

3.1 类型定义骨架

先建一个src/types/tui-thread-cmd.ts，把WithDoubleDash和TuiThreadCmd写清楚。核心思路是：用泛型T表示全局 argv，用U表示当前命令参数，然后在CommandModule的第二个槽位做交叉。

import type { CommandModule, Argv, Arguments } from "yargs"; // 把 "--" 属性补进命令参数类型 export type WithDoubleDash<U> = U & { "--"?: string[] }; // TuiThreadCmd 的结构化类型骨架 export interface TuiThreadCmdShape<T, U> { command: string | string[]; describe?: string; builder?: (yargs: Argv<T>) => Argv<U>; handler: (argv: Arguments<WithDoubleDash<U>>) => void | Promise<void>; } // identity 函数：保留原始类型的同时注入 "--" export function tuiThreadCmd<T, U>( input: CommandModule<T, WithDoubleDash<U>> ): CommandModule<T, WithDoubleDash<U>> { return input; }

这里tuiThreadCmd是一个泛型 identity 函数。它没有显式写返回类型，TypeScript 根据return input自动推断返回值就是CommandModule<T, WithDoubleDash<U>>。关键在第二个泛型参数位置：不是直接传U，而是先做WithDoubleDash<U>变换再传。

3.2 实际命令对象

在src/commands/thread.ts里这样写：

import { tuiThreadCmd } from "../types/tui-thread-cmd"; export const threadCommand = tuiThreadCmd({ command: "thread <action>", describe: "管理 TUI 线程", builder: (yargs) => yargs .positional("action", { type: "string", choices: ["list", "attach", "detach"] as const, }) .option("thread-id", { type: "string", describe: "线程 ID", }) .option("verbose", { type: "boolean", default: false, }), handler: async (argv) => { // argv.action 被推断为 "list" | "attach" | "detach" // argv.threadId 被推断为 string | undefined // argv["--"] 被推断为 string[] | undefined if (argv.verbose) { console.log("action:", argv.action, "thread:", argv.threadId); } console.log("透传参数:", argv["--"]); }, });

注意argv.threadId是 camelCase，yargs 会自动把--thread-id转成threadId。argv["--"]能通过类型检查，正是因为WithDoubleDash<U>补上了这个属性。

3.3 settings.json 配置片段

OpenCode Agent 的本地配置放在项目根目录settings.json，把模型调用和命令注册都写进去：

{ "agent": { "commands": ["./src/commands/thread.ts"], "model": { "provider": "taotoken", "baseURL": "https://taotoken.net/api", "apiKeyEnv": "TAOTOKEN_API_KEY", "model": "claude-sonnet-4-20250514" } }, "typescript": { "strict": true, "noImplicitAny": true } }

环境变量在 shell 里设置：

export TAOTOKEN_API_KEY="你的Key"

提示：baseURL只写https://taotoken.net/api，不要加 UTM 参数，避免请求路径被污染。

4. 验证请求：跑通类型检查与调用链路

4.1 类型检查

先确认tsconfig.json开了 strict：

{ "compilerOptions": { "strict": true, "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler", "noEmit": true } }

然后跑：

npx tsc --noEmit

如果handler里访问argv["--"]没有报错，说明WithDoubleDash<U>生效了。你可以故意把WithDoubleDash去掉，再跑一次，会看到Property '--' does not exist on type ...，这就是类型补丁在起作用。

4.2 调用链路验证

写一个最小入口src/cli.ts：

import yargs from "yargs"; import { hideBin } from "yargs/helpers"; import { threadCommand } from "./commands/thread"; yargs(hideBin(process.argv)) .command(threadCommand) .parserConfiguration({ "populate--": true }) .demandCommand(1) .help() .parse();

运行：

npx tsx src/cli.ts thread list --thread-id abc -- --extra=1

预期输出：

action: list thread: abc 透传参数: [ '--extra=1' ]

--后面的内容被populate--收集进argv["--"]，类型上是string[] | undefined，运行时是数组。这一步同时验证了类型定义和 yargs 运行时配置的强绑定关系：populate--是运行时开关，WithDoubleDash<U>是编译期类型补丁，缺一不可。

4.3 模型调用验证

在 handler 里加一段模型请求，确认 TaoToken 链路通：

handler: async (argv) => { const res = await fetch("https://taotoken.net/api/v1/messages", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": process.env.TAOTOKEN_API_KEY!, "anthropic-version": "2023-06-01", }, body: JSON.stringify({ model: "claude-sonnet-4-20250514", max_tokens: 64, messages: [{ role: "user", content: "ping" }], }), }); console.log(await res.json()); },

跑npx tsx src/cli.ts thread list，能看到模型返回就说明整条链路通了。

5. 本篇常见错排查

5.1argv["--"]报属性不存在

原因：CommandModule的第二个泛型槽位直接传了U，没做WithDoubleDash<U>变换。yargs 原生类型默认不包含"--"，因为--的行为由parserConfiguration决定，是可选行为。类型定义无法根据运行时调用动态变化，所以它选择保守策略。

解决：确认tuiThreadCmd签名里写的是CommandModule<T, WithDoubleDash<U>>，而不是CommandModule<T, U>。

5.2argv.threadId推断为 unknown

原因：builder返回的Argv<U>没有被正确推导。常见于 builder 里用了as any或返回了yargs本身而没有链式调用。

解决：builder 必须返回yargs.option(...)的链式结果，不要中途return yargs as any。如果选项很多，可以拆成多个.option()链式调用。

5.3 类型检查过了但运行时argv["--"]是 undefined

原因：parserConfiguration({ "populate--": true })没加，或者加在了.command()之后但没作用到子命令。

解决：把parserConfiguration放在.command()之前，确保全局生效。运行时开关和编译期类型补丁必须同时存在。

5.4tsc报CommandModule不是类型

原因：import type { CommandModule } from "yargs"写成了import { CommandModule }，在某些打包配置下会被当成值导入。

解决：统一用import type导入纯类型。Argv、Arguments、CommandModule都是类型，不需要运行时值。

5.5 模型请求 401

原因：TAOTOKEN_API_KEY没设置，或者 header 名写错。Anthropic 风格用x-api-key，OpenAI 风格用Authorization: Bearer。

解决：先echo $TAOTOKEN_API_KEY确认环境变量存在，再检查 header。API Key 在 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 创建。

6. 继续往下走：类型稳定后再接模型

TuiThreadCmd 的结构化类型本质上是给 yargs 的CommandModule打了一个类型补丁，让"--"属性能在 handler 里被安全访问。类型骨架稳定之后，你可以把模型调用、日志、错误处理都塞进 handler，而不用担心 argv 形状漂移。

如果你在排障或接入阶段卡住，先看 API Keys 和接入文档：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 和 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。想先验证模型返回格式，用模型对话页：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。长期跑编码 Agent 的话，Coding Plan 在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。

我自己的习惯是：类型检查通过后，先在 handler 里打一行console.log(JSON.stringify(argv, null, 2))，确认运行时形状和类型推断一致，再接模型。这一步能省掉大量“类型对了但运行时不对”的排查时间。