1. 为什么 OpenCode 插件开发需要公共工具库
写过三五个 OpenCode 插件之后，你大概率会进入一种“复制粘贴循环”：新插件一开，先把上一个插件里的日志封装、缓存逻辑、重试包装、错误兜底整段搬过来，改改变量名就继续写业务。单次看没什么问题，但插件数量一多，问题就集中爆发——同一个重试 bug 要在五个文件里各修一遍，日志格式每个插件都不一样，排查线上问题时根本串不起来。
这一篇要解决的就是这件事：把 OpenCode 插件开发里反复出现的横切逻辑，抽成一套可复用的 TypeScript 工具函数与装饰器库，再配合 TaoToken 统一 Key 接入，让每个新插件从“搭基础设施”变成“只写业务”。核心检索词先摆出来：OpenCode 插件开发、公共工具函数、装饰器库、TypeScript 类型约束、TaoToken 统一 Key 接入。适合已经能写单个插件、但被重复代码拖慢节奏的开发者。
我试过最笨的办法——每个插件单独维护一份 utils，结果三个月后自己都分不清哪份是最新的。后来改成 monorepo 里一个独立的opencode-utils包，所有插件通过 workspace 依赖引用，改一处全局生效，才算真正把开发效率拉起来。
工具库的价值分两层。短期看，写第一个插件时你少写日志、缓存、重试、错误处理这四类样板代码，bug 面直接缩小；长期看，所有插件共享同一套“最佳实践”，新成员加入时不用逐个读插件源码去猜约定，直接看工具库的类型定义就懂。更关键的是，当你要接入 TaoToken 这类统一 API 通道时，鉴权、Base URL、模型 ID 这些配置只需要在工具库层封装一次，插件侧调用的是语义化函数，而不是散落各处的 fetch。
这里要提醒一点：工具库不是“写完就冻结”的产物。它是一个活代码库，随着你写的插件越来越多，会不断发现新的可复用模式——比如参数校验、并发限流、结果格式化。所以目录结构从一开始就要按功能分模块，而不是堆在一个utils.ts里。下面从目录设计开始，一步步把日志、缓存、重试、安全执行、装饰器全部落地，最后用一个完整插件验证整套工具库 + TaoToken 接入是否跑通。
2. TaoToken 前置准备与统一 Key 接入配置
在动手写工具库之前，先把 API 通道这层理顺。OpenCode 插件里只要涉及模型调用，就会碰到 Base URL、API Key、Model ID 三件套。如果每个插件各自读环境变量、各自拼请求，配置漂移几乎不可避免。TaoToken 在这里的角色是提供统一的 API 入口，让工具库层集中管理鉴权与请求封装。
先拿 Key。打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。创建后立刻复制保存，页面刷新后不再完整显示。
拿到 Key 之后，不要硬编码进插件源码。推荐放在项目根目录的.env里，由工具库统一读取：
# .env TAOTOKEN_API_KEY=sk-你的实际Key TAOTOKEN_BASE_URL=https://taotoken.net/api TAOTOKEN_MODEL_ID=claude-sonnet-4-5注意 Base URL 用https://taotoken.net/api，不带任何查询参数。Model ID 按你实际开通的模型填写，控制台模型列表里能看到准确名称。如果你用 Claude Code 做编码辅助，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有 Base URL 与鉴权头的完整说明。
工具库层封装一个createTaoTokenClient，把三件套收敛到一个工厂函数里：
// src/taotoken/client.ts export interface TaoTokenConfig { apiKey: string baseUrl: string modelId: string timeout?: number } export interface ChatMessage { role: 'system' | 'user' | 'assistant' content: string } export function createTaoTokenClient(config: TaoTokenConfig) { const { apiKey, baseUrl, modelId, timeout = 60000 } = config async function chat(messages: ChatMessage[]): Promise<string> { const controller = new AbortController() const timer = setTimeout(() => controller.abort(), timeout) try { const res = await fetch(`${baseUrl}/v1/messages`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey, 'anthropic-version': '2023-06-01' }, body: JSON.stringify({ model: modelId, max_tokens: 4096, messages }), signal: controller.signal }) if (!res.ok) { throw new Error(`TaoToken 请求失败: ${res.status} ${res.statusText}`) } const data = await res.json() return data.content?.[0]?.text ?? '' } finally { clearTimeout(timer) } } return { chat, modelId } }这段代码的关键点：鉴权头用x-api-key，版本头anthropic-version固定，Base URL 与 Model ID 全部来自配置对象，插件侧不感知具体值。这样以后换模型或换通道，只改.env和工具库一处。
如果你打算长期跑编码类 Agent 任务，Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 里有套餐与额度说明，按调用量选即可。想先在网页里验证模型是否通，用模型对话 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 发一条消息，能正常返回就说明 Key 和通道没问题，再回到代码里接。
3. 可复制的工具库目录结构与装饰器实现
目录结构决定了工具库能不能长期维护。按功能分模块，每个模块一个index.ts，装饰器单独放一层，类型定义集中管理：
opencode-utils/ ├── src/ │ ├── index.ts # 主入口，统一导出 │ ├── logger/index.ts # 结构化日志 │ ├── cache/index.ts # 带 TTL 的内存缓存 │ ├── retry/index.ts # 指数退避重试 │ ├── safe/index.ts # 安全执行与错误兜底 │ ├── taotoken/client.ts # TaoToken 统一客户端 │ ├── decorators/index.ts # 日志/缓存/重试装饰器 │ └── types/index.ts # 共享类型 ├── test/unit/ ├── package.json ├── tsconfig.json └── README.md创建命令：
mkdir -p src/{logger,cache,retry,safe,taotoken,decorators,types} mkdir -p test/unit touch src/index.tstsconfig.json必须开启装饰器支持，否则后面@Log()这类语法直接编译报错：
{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", "experimentalDecorators": true, "emitDecoratorMetadata": true, "strict": true, "declaration": true, "outDir": "dist", "paths": { "@utils/*": ["./src/*"] } }, "include": ["src/**/*.ts"] }日志模块用工厂函数返回独立实例，每个插件可以带自己的前缀和级别：
// src/logger/index.ts export type LogLevel = 'debug' | 'info' | 'warn' | 'error' const priority: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 } export function createLogger(prefix = '[OpenCode]', level: LogLevel = 'info') { const should = (l: LogLevel) => priority[l] >= priority[level] const fmt = (l: LogLevel, msg: string) => `[${new Date().toISOString()}]${prefix} ${l.toUpperCase().padEnd(5)} ${msg}` return { debug: (m: string, ...a: unknown[]) => should('debug') && console.debug(fmt('debug', m), ...a), info: (m: string, ...a: unknown[]) => should('info') && console.info(fmt('info', m), ...a), warn: (m: string, ...a: unknown[]) => should('warn') && console.warn(fmt('warn', m), ...a), error: (m: string, e?: Error, ...a: unknown[]) => should('error') && console.error(fmt('error', m), e?.stack ?? e, ...a) } }缓存模块带 TTL 和定时清理，避免内存泄漏：
// src/cache/index.ts interface Item<T> { value: T; expiresAt: number } export function createCache<T = unknown>(defaultTTL = 300000) { const store = new Map<string, Item<T>>() const timer = setInterval(() => { const now = Date.now() for (const [k, v] of store) if (v.expiresAt < now) store.delete(k) }, 60000) return { set: (k: string, v: T, ttl = defaultTTL) => store.set(k, { value: v, expiresAt: Date.now() + ttl }), get: (k: string): T | undefined => { const item = store.get(k) if (!item) return undefined if (item.expiresAt < Date.now()) { store.delete(k); return undefined } return item.value }, delete: (k: string) => store.delete(k), clear: () => store.clear(), dispose: () => clearInterval(timer) } }重试模块用指数退避加随机抖动，防止重试风暴：
// src/retry/index.ts export interface RetryConfig { maxAttempts: number initialDelay: number maxDelay: number multiplier: number } const defaults: RetryConfig = { maxAttempts: 5, initialDelay: 1000, maxDelay: 30000, multiplier: 2 } export async function withRetry<T>(fn: () => Promise<T>, cfg: Partial<RetryConfig> = {}): Promise<T> { const c = { ...defaults, ...cfg } let delay = c.initialDelay let last: Error | null = null for (let i = 1; i <= c.maxAttempts; i++) { try { return await fn() } catch (e) { last = e instanceof Error ? e : new Error(String(e)) if (i === c.maxAttempts) break const wait = Math.min(delay + Math.random() * 200, c.maxDelay) console.warn(`第 ${i} 次失败: ${last.message}，${Math.round(wait)}ms 后重试`) await new Promise(r => setTimeout(r, wait)) delay = Math.min(delay * c.multiplier, c.maxDelay) } } throw last }安全执行模块把异常转成结构化结果，插件不会因为一个未捕获异常整体崩溃：
// src/safe/index.ts export type SafeResult<T> = | { success: true; data: T } | { success: false; error: Error; message: string } export async function safe<T>(fn: () => Promise<T>): Promise<SafeResult<T>> { try { return { success: true, data: await fn() } } catch (e) { const err = e instanceof Error ? e : new Error(String(e)) return { success: false, error: err, message: err.message } } }装饰器层把上面四个模块串起来，让业务方法一行注解就获得日志、缓存、重试能力：
// src/decorators/index.ts import { createLogger, type LogLevel } from '../logger' import { createCache } from '../cache' import { withRetry, type RetryConfig } from '../retry' export function Log(level: LogLevel = 'info') { return (_t: unknown, key: string, desc: PropertyDescriptor) => { const original = desc.value desc.value = async function (...args: unknown[]) { const log = createLogger(`[${this.constructor.name}]`) const start = Date.now() log[level](`调用 ${key}`, args) try { const r = await original.apply(this, args) log[level](`${key} 完成，耗时 ${Date.now() - start}ms`) return r } catch (e) { log.error(`${key} 失败 (${Date.now() - start}ms)`, e as Error) throw e } } return desc } } export function Cache(ttl = 300000) { return (_t: unknown, key: string, desc: PropertyDescriptor) => { const original = desc.value const cache = createCache(ttl) desc.value = async function (...args: unknown[]) { const k = `${key}(${JSON.stringify(args)})` const hit = cache.get(k) if (hit !== undefined) return hit const r = await original.apply(this, args) cache.set(k, r) return r } return desc } } export function Retry(cfg: Partial<RetryConfig> = {}) { return (_t: unknown, _k: string, desc: PropertyDescriptor) => { const original = desc.value desc.value = async function (...args: unknown[]) { return withRetry(() => original.apply(this, args), cfg) } return desc } }主入口统一导出，插件侧只 import 一个包：
// src/index.ts export { createLogger } from './logger' export { createCache } from './cache' export { withRetry } from './retry' export { safe } from './safe' export { createTaoTokenClient } from './taotoken/client' export { Log, Cache, Retry } from './decorators' export type { LogLevel } from './logger' export type { RetryConfig } from './retry' export type { SafeResult } from './safe' export type { TaoTokenConfig, ChatMessage } from './taotoken/client'4. 在 OpenCode 插件中调用与验证完整流程
工具库写完后，用一个真实插件验证。目标：写一个“代码解释”插件，调用 TaoToken 的模型通道，把用户选中的代码片段解释成自然语言，同时用上日志、缓存、重试、安全执行和装饰器。
插件文件放在.opencode/plugins/code-explainer.ts：
import type { Plugin } from '@opencode-ai/plugin' import { tool } from '@opencode-ai/plugin' import { createLogger, createTaoTokenClient, safe, Log, Cache, Retry } from '../../opencode-utils/src/index' const log = createLogger('[CodeExplainer]', 'debug') const client = createTaoTokenClient({ apiKey: process.env.TAOTOKEN_API_KEY!, baseUrl: process.env.TAOTOKEN_BASE_URL ?? 'https://taotoken.net/api', modelId: process.env.TAOTOKEN_MODEL_ID ?? 'claude-sonnet-4-5' }) class ExplainerService { @Log('info') @Cache(600000) @Retry({ maxAttempts: 3, initialDelay: 1500 }) async explain(code: string, language: string): Promise<string> { return client.chat([ { role: 'system', content: '你是代码解释助手，用简洁中文说明代码意图、关键逻辑和潜在问题。' }, { role: 'user', content: `语言: ${language}\n代码:\n${code}` } ]) } } const service = new ExplainerService() export const CodeExplainerPlugin: Plugin = async () => { log.info('CodeExplainer 插件加载中') return { tool: { explain_code: tool({ description: '解释一段代码的功能、逻辑和潜在问题。当用户想理解某段代码时使用。', args: { code: tool.schema.string().describe('要解释的代码片段'), language: tool.schema.string().optional().describe('编程语言，如 typescript、python') }, async execute(args) { const language = args.language ?? 'typescript' log.debug('收到解释请求', { language, length: args.code.length }) const result = await safe(() => service.explain(args.code, language)) if (result.success) { log.info('解释完成') return result.data } log.error('解释失败', result.error) return `解释失败: ${result.message}。请稍后重试。` } }) } } }验证分三步。第一步，确认环境变量已加载，在插件目录执行：
node -e "console.log(process.env.TAOTOKEN_API_KEY ? 'Key 已加载' : 'Key 缺失')"第二步，启动 OpenCode，观察终端是否输出[CodeExplainer] 插件加载中。如果没看到，说明插件路径或导出名不对。
第三步，在 TUI 里输入“帮我解释这段代码”，粘贴一段 TypeScript，观察返回。第一次调用会看到调用 explain和explain 完成，耗时 xxxms两条日志；连续第二次相同代码，会命中缓存，耗时明显下降，且不会再次发起网络请求。
如果模型通道有问题，先用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 单独验证 Key 是否可用，排除是插件代码问题还是通道问题。想确认模型 ID 是否写对，接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 里有当前可用模型清单。
5. 本篇常见报错排查
报错一：Decorators are not valid here
完整报错类似error TS1206: Decorators are not valid here。原因是tsconfig.json没开experimentalDecorators。解决：确认compilerOptions里有"experimentalDecorators": true和"emitDecoratorMetadata": true。如果你用 Bun 或 ts-node 运行，还要确认运行时也支持装饰器；Bun 默认支持，ts-node 需要配合--compiler-options或 tsconfig 生效。不想用装饰器语法的话，直接用withRetry、createCache这些高阶函数，功能等价。
报错二：Cannot find module '../../opencode-utils/src/index'
模块路径找不到。先确认工具库目录真实存在：
ls -la opencode-utils/src/index.ts再确认插件里的相对路径层级。插件在.opencode/plugins/下，工具库在项目根opencode-utils/，从插件到工具库是../../opencode-utils/src/index。如果层级不对，用paths映射简化：
{ "compilerOptions": { "paths": { "@utils/*": ["./opencode-utils/src/*"] } } }然后改成import { ... } from '@utils/index'。
报错三：401 Unauthorized或local proxy failed
401 说明 Key 没被正确读取或已失效。检查.env是否被加载，TAOTOKEN_API_KEY是否有值，请求头是否用了x-api-key。local proxy failed通常是 Base URL 写错，确认是https://taotoken.net/api，不要多加/v1或查询参数。如果报错里出现reading 'choices'，说明响应结构和你解析的字段不匹配，检查返回体是content[0].text还是choices[0].message.content，按实际通道文档调整解析。
报错四：OAuth相关报错
如果你在 Claude Code 或 Codex 里配置过 OAuth，可能出现鉴权冲突。检查~/.codex/auth.json或 Claude Code 的 settings 里是否残留旧凭据。统一走 TaoToken 的 API Key 模式时，把 Base URL、Key、Model ID 三件套都指向 TaoToken，不要混用两套鉴权。Codex 的auth.json里如果同时存在 OAuth token 和 API Key，优先清理 OAuth 字段。
报错五：缓存导致内存持续增长
运行一段时间后内存占用只增不减。检查每个createCache实例是否设置了合理 TTL，以及插件卸载时是否调用了dispose()。工具库里的定时清理每分钟跑一次，但如果 TTL 设成几小时，过期项会长期驻留。对大数据量场景，把Map换成 LRU 实现，或在插件dispose钩子里显式cache.clear()。
6. 统一 Key 接入与工具库的长期维护
工具库跑通之后，维护节奏比一次性写完更重要。我的做法是：每写一个新插件，如果发现某段逻辑在两个以上插件里重复出现，就把它抽进工具库，同时补一个单元测试。这样工具库是“用出来”的，而不是一开始拍脑袋设计一堆用不上的抽象。
TaoToken 统一 Key 这层的维护要点：所有插件只依赖createTaoTokenClient，不直接读环境变量、不直接拼 URL。换模型时改.env里的TAOTOKEN_MODEL_ID；换通道时改TAOTOKEN_BASE_URL；Key 轮换时改TAOTOKEN_API_KEY。插件代码零改动。如果你有多个项目共用一套 Key，把工具库发布成私有 npm 包，各项目通过版本号升级，避免复制粘贴导致的配置漂移。
长期跑编码类 Agent 任务的话，Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 里可以按调用量规划额度，比单次充值更好控制成本。需要新建或轮换 Key 时，API Keys 页面 https://taotoken.net/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 ，Base URL、鉴权头、模型 ID 都有对照表。
最后给一个实用技巧：在工具库的README.md里维护一张“能力清单”表格，列出每个模块解决什么问题、对应导出函数、典型用法一行示例。新插件开发时先扫这张表，能复用就不重写。工具库的价值不在于代码多，而在于你写第二个、第三个插件时，真的会去用它。
