OpenCLI 二次开发实战：TypeScript 适配器设计与 AI Agent 工具链整合

1. 为什么我要折腾 OpenCLI 的二次开发

第一次接触 OpenCLI 是在一个内部工具链整合的项目里。当时团队需要把几个自研的运维平台、文档系统和数据看板统一到一个命令行入口，让 AI Agent 能够通过自然语言直接调用这些系统的能力。市面上的方案要么太重，要么扩展性差，直到发现 OpenCLI 这个项目——它本质上是一个把「命令行工具」和「AI 能力」桥接起来的框架，核心思路是用 TypeScript 定义一套适配器规范，让任意网站或服务都能被包装成 AI 可调用的工具。

这个定位非常精准。你可以把它理解成一个「万能转接头」：左边是各种形态的网站、API、内部系统，右边是 AI 大模型的函数调用能力，中间靠适配器层做协议转换。我实测下来，一个中等复杂度的适配器，从零到能跑通，熟练的话两三个小时就能搞定。对于做 AI Agent 开发、想给自己的产品加上「AI 调用外部能力」这个特性的同学来说，这套东西的投入产出比相当高。

但问题也很明显。官方文档覆盖的是「标准场景」，一旦你要接入的网站有登录态、有反爬、有复杂的参数签名，或者你想把多个适配器编排成工作流，文档就力不从心了。网上关于 OpenCLI 二次开发的中文资料几乎为零，TypeScript 适配器怎么写、规划适配器怎么设计、遇到类型报错怎么排查，全靠自己啃源码和试错。我踩过的坑包括但不限于：适配器返回值类型不匹配导致 AI 调用静默失败、异步操作没处理好导致超时、参数校验缺失导致注入风险。

所以这篇内容，我想把这段时间在 OpenCLI 二次开发上的实战经验完整梳理一遍。从适配器的核心设计思路，到 TypeScript 类型系统的实战用法，再到具体接入一个真实网站的完整流程，最后是排查问题的速查表。适合已经了解 OpenCLI 基本概念、想深入做二次开发的工程师，也适合正在做 AI Agent 工具链整合、需要一套可扩展适配器方案的技术负责人。读完之后，你应该能独立完成一个生产可用的适配器，并且知道遇到问题该往哪个方向查。

2. OpenCLI 适配器的核心设计思路拆解

2.1 适配器到底在解决什么问题

很多人第一次看 OpenCLI 的适配器概念会懵：不就是调个 API 吗，为什么还要搞一层适配器？这里的关键在于「AI 可调用」和「人能调用」是两回事。

人调用一个网站，可以打开浏览器、登录、点按钮、填表单、看结果，中间有大量的隐式上下文。但 AI 调用一个工具，它只认函数签名：输入什么参数、返回什么结构、有没有副作用。适配器的本质工作，就是把这中间的「隐式上下文」显式化、结构化、类型化。

举个具体例子。假设你要让 AI 能查询某个内部工单系统的工单状态。人操作的话，流程是：登录系统 → 进入工单列表 → 输入工单号 → 查看状态。但 AI 需要的是一个函数：queryTicketStatus(ticketId: string): Promise<TicketStatus>。适配器要做的就是把这个函数背后的登录态管理、请求构造、响应解析全部封装起来，对外只暴露一个干净的、带类型定义的函数。

这就是为什么 OpenCLI 选择 TypeScript 作为适配器的定义语言。TypeScript 的类型系统能在编译期就发现「AI 传参类型不对」「返回值结构不匹配」这类问题，而不是等到运行时才报错。我试过用纯 JavaScript 写适配器，结果就是各种undefined is not a function在运行时才暴露，排查成本极高。

2.2 规划适配器的分层架构

一个生产级的 OpenCLI 适配器，我习惯把它拆成四层。这个分层不是官方强制的，但实测下来能极大降低维护成本。

第一层是协议层，负责和外部系统通信。HTTP 请求、WebSocket 连接、gRPC 调用都属于这一层。这一层的关键是「可替换」——今天用 axios，明天想换成 fetch，不应该影响上层。

第二层是认证层，处理登录态、Token 刷新、Cookie 管理。这是最容易出问题的地方。很多网站的 Token 有有效期，适配器必须能自动刷新，否则 AI 调用到一半突然 401，整个流程就断了。

第三层是业务层，把外部系统的原始接口包装成有业务语义的函数。比如把POST /api/v1/ticket/query包装成queryTicketStatus。这一层要处理参数校验、错误码映射、返回值归一化。

第四层是适配层，也就是 OpenCLI 要求的适配器接口实现。这一层只做一件事：把业务层的函数注册成 OpenCLI 能识别的工具定义，包括名称、描述、参数 schema。

这样分层的好处是，当外部系统接口变了，你只需要改业务层；当认证方式变了，只改认证层；OpenCLI 框架升级了，只改适配层。我见过把所有逻辑堆在一个文件里的适配器，改一个参数要翻三百行代码，维护起来非常痛苦。

2.3 为什么类型定义是二次开发的重中之重

OpenCLI 的适配器开发，TypeScript 类型定义不是「锦上添花」，而是「生死攸关」。原因在于 AI 调用工具时，参数是通过 JSON Schema 描述的，而 TypeScript 类型是编译期的约束。这两者之间需要一层映射，如果映射不准确，就会出现 AI 传了参数但适配器收不到、或者适配器返回了数据但 AI 解析不了的情况。

我踩过最典型的一个坑：适配器定义了一个可选参数options?: { timeout?: number }，但在注册工具时没有正确生成 JSON Schema，导致 AI 认为这个参数不存在，永远不会传。排查了半天才发现是 schema 生成的问题。

所以我的经验是：适配器的类型定义要尽可能扁平化，避免深层嵌套的可选对象。AI 对嵌套结构的理解能力有限，扁平化的参数设计能显著提高调用成功率。如果确实需要复杂参数，拆成多个工具函数比一个复杂函数更可靠。

3. TypeScript 适配器开发的核心细节与实操要点

3.1 适配器接口的最小实现

先看一个最小可用的适配器长什么样。OpenCLI 的适配器接口通常要求实现几个核心方法：工具列表声明、工具调用执行、以及可选的初始化逻辑。

import { Adapter, ToolDefinition, ToolCallResult } from 'opencli-core'; interface QueryParams { keyword: string; limit?: number; } export class SearchAdapter implements Adapter { name = 'search-adapter'; version = '1.0.0'; private baseUrl: string; constructor(baseUrl: string) { this.baseUrl = baseUrl; } getTools(): ToolDefinition[] { return [ { name: 'search_items', description: '根据关键词搜索条目，返回匹配的结果列表', parameters: { type: 'object', properties: { keyword: { type: 'string', description: '搜索关键词，必填' }, limit: { type: 'number', description: '返回结果数量上限，默认 10' } }, required: ['keyword'] } } ]; } async callTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult> { if (name !== 'search_items') { return { success: false, error: `未知工具: ${name}` }; } const params = args as unknown as QueryParams; if (!params.keyword || typeof params.keyword !== 'string') { return { success: false, error: 'keyword 参数缺失或类型错误' }; } const limit = params.limit ?? 10; try { const response = await fetch( `${this.baseUrl}/search?q=${encodeURIComponent(params.keyword)}&limit=${limit}` ); if (!response.ok) { return { success: false, error: `请求失败: ${response.status}` }; } const data = await response.json(); return { success: true, data }; } catch (err) { return { success: false, error: `请求异常: ${(err as Error).message}` }; } } }

这段代码看起来简单，但有几个细节值得展开说。

getTools()返回的parameters字段，就是给 AI 看的 JSON Schema。这里的description写得越清楚，AI 调用时越不容易出错。我习惯在 description 里明确写出「必填」「默认值」「格式要求」，实测能显著降低 AI 传错参数的概率。

callTool里的参数校验不能省。虽然 TypeScript 有类型系统，但 AI 传来的参数是运行时数据，类型断言as unknown as QueryParams只是告诉编译器「我知道我在干什么」，并不做实际校验。所以必须手动检查关键参数的存在性和类型。

3.2 认证层的 Token 管理实战

接入需要登录的网站时，认证层是绕不过去的。我总结了一套「懒加载 + 自动刷新」的 Token 管理模式，实测比较稳。

核心思路是：不在适配器初始化时就登录，而是等到第一次调用工具时才触发登录；Token 快过期时自动刷新，而不是等 401 了再处理。

class TokenManager { private token: string | null = null; private expiresAt: number = 0; private refreshPromise: Promise<string> | null = null; constructor( private loginFn: () => Promise<{ token: string; expiresIn: number }> ) {} async getToken(): Promise<string> { const now = Date.now(); // 提前 60 秒刷新，避免边界情况 if (this.token && now < this.expiresAt - 60_000) { return this.token; } // 防止并发刷新 if (!this.refreshPromise) { this.refreshPromise = this.doRefresh(); } try { return await this.refreshPromise; } finally { this.refreshPromise = null; } } private async doRefresh(): Promise<string> { const result = await this.loginFn(); this.token = result.token; this.expiresAt = Date.now() + result.expiresIn * 1000; return this.token; } }

这里有两个关键点。第一是提前刷新：不要等到 Token 完全过期才刷新，留 60 秒缓冲，避免请求发出时还有效、到达服务器时已过期的尴尬情况。第二是并发控制：如果多个工具调用同时发现 Token 过期，不能让它们各自去登录，否则会触发多次登录请求，有些网站会因此封号。用一个refreshPromise做单飞（single-flight），保证同一时间只有一个刷新请求。

注意：有些网站的登录接口有频率限制，如果适配器被高频调用，Token 刷新策略要更保守。我一般会把提前刷新时间设成 Token 有效期的 20%，比如 Token 有效期 1 小时，就提前 12 分钟刷新。

3.3 参数校验与错误处理的正确姿势

AI 调用工具时，参数出错是常态。可能是 AI 理解错了工具描述，可能是用户输入了奇怪的字符，也可能是网络传输中数据被截断。适配器必须能优雅地处理这些情况，而不是直接抛异常。

我的做法是写一个通用的参数校验函数，在callTool入口处统一调用：

function validateParams<T extends Record<string, unknown>>( args: Record<string, unknown>, schema: { required: string[]; types: Record<string, string> } ): { valid: true; data: T } | { valid: false; error: string } { for (const key of schema.required) { if (args[key] === undefined || args[key] === null) { return { valid: false, error: `缺少必填参数: ${key}` }; } } for (const [key, expectedType] of Object.entries(schema.types)) { if (args[key] !== undefined && typeof args[key] !== expectedType) { return { valid: false, error: `参数 ${key} 类型错误，期望 ${expectedType}，实际 ${typeof args[key]}` }; } } return { valid: true, data: args as T }; }

错误返回的格式也很重要。OpenCLI 的ToolCallResult里，error字段的内容会直接反馈给 AI。所以错误信息要写得让 AI 能理解、能自我纠正。比如「缺少必填参数: keyword」就比「参数错误」有用得多，AI 看到前者会知道要补上 keyword 参数。

3.4 返回值归一化的经验

不同网站的返回结构千差万别，但 AI 期望的是相对统一的结构。适配器的业务层要做的一件事，就是把各种奇形怪状的响应归一化成 AI 容易理解的形式。

我的经验是：返回值尽量用扁平的对象数组，避免深层嵌套。比如一个搜索接口返回了{ data: { list: { items: [...] } } }，适配器应该把它拍平成{ results: [...] }。AI 对扁平结构的解析准确率明显更高。

另外，返回的数据量要控制。有些接口一次返回几百条记录，直接丢给 AI 会撑爆上下文窗口。适配器应该做分页或截断，并在返回值里明确告知「还有更多结果」。我一般会把单次返回控制在 20 条以内，并在返回结构里加一个hasMore: boolean字段。

4. 完整实操：从零接入一个真实网站

4.1 前期调研与接口分析

接入任何网站之前，第一步永远是调研。我习惯用浏览器的开发者工具，把目标网站的关键请求抓出来，重点看四个东西：请求 URL、请求方法、请求头（尤其是认证相关的）、请求体和响应体结构。

假设我们要接入一个内部的文档管理系统，目标是让 AI 能搜索文档。通过开发者工具，我抓到了搜索接口：

POST /api/docs/search Headers: Content-Type: application/json Authorization: Bearer <token> Body: { "query": "关键词", "page": 1, "pageSize": 20 } Response: { "code": 0, "data": { "total": 156, "items": [ { "id": "doc_001", "title": "文档标题", "url": "/docs/doc_001", "updatedAt": "2024-01-15" } ] } }

同时我注意到，登录接口是POST /api/auth/login，返回{ token: "...", expiresIn: 3600 }。这些信息就足够设计适配器了。

调研阶段有个容易忽略的点：要确认接口是否有频率限制。有些网站会在响应头里返回X-RateLimit-Remaining之类的字段，如果没注意，适配器上线后可能因为高频调用被封。我一般会在调研时故意快速请求几次，观察是否有限流响应。

4.2 适配器代码的完整实现

基于调研结果，完整的适配器实现如下。我把认证、业务、适配三层都写在一个文件里，方便你直接参考，实际项目中建议拆成多个文件。

import { Adapter, ToolDefinition, ToolCallResult } from 'opencli-core'; interface DocItem { id: string; title: string; url: string; updatedAt: string; } interface SearchResult { total: number; results: DocItem[]; hasMore: boolean; } class DocSystemAdapter implements Adapter { name = 'doc-system-adapter'; version = '1.0.0'; private baseUrl: string; private username: string; private password: string; private token: string | null = null; private tokenExpiresAt = 0; private loginPromise: Promise<void> | null = null; constructor(config: { baseUrl: string; username: string; password: string }) { this.baseUrl = config.baseUrl.replace(/\/$/, ''); this.username = config.username; this.password = config.password; } private async ensureToken(): Promise<void> { if (this.token && Date.now() < this.tokenExpiresAt - 60_000) { return; } if (!this.loginPromise) { this.loginPromise = this.doLogin(); } try { await this.loginPromise; } finally { this.loginPromise = null; } } private async doLogin(): Promise<void> { const response = await fetch(`${this.baseUrl}/api/auth/login`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ username: this.username, password: this.password }) }); if (!response.ok) { throw new Error(`登录失败: HTTP ${response.status}`); } const data = await response.json(); if (!data.token) { throw new Error('登录响应缺少 token 字段'); } this.token = data.token; this.tokenExpiresAt = Date.now() + (data.expiresIn ?? 3600) * 1000; } getTools(): ToolDefinition[] { return [ { name: 'search_docs', description: '在文档系统中搜索文档，返回匹配的文档列表。支持分页。', parameters: { type: 'object', properties: { query: { type: 'string', description: '搜索关键词，必填，不能为空字符串' }, page: { type: 'number', description: '页码，从 1 开始，默认 1' }, pageSize: { type: 'number', description: '每页数量，默认 20，最大 50' } }, required: ['query'] } } ]; } async callTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult> { if (name !== 'search_docs') { return { success: false, error: `未知工具: ${name}` }; } const query = args.query; if (typeof query !== 'string' || query.trim() === '') { return { success: false, error: 'query 参数必须是非空字符串' }; } const page = typeof args.page === 'number' ? Math.max(1, Math.floor(args.page)) : 1; const pageSize = typeof args.pageSize === 'number' ? Math.min(50, Math.max(1, Math.floor(args.pageSize))) : 20; try { await this.ensureToken(); const response = await fetch(`${this.baseUrl}/api/docs/search`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${this.token}` }, body: JSON.stringify({ query: query.trim(), page, pageSize }) }); if (response.status === 401) { // Token 失效，强制刷新后重试一次 this.token = null; await this.ensureToken(); return this.callTool(name, args); } if (!response.ok) { return { success: false, error: `搜索请求失败: HTTP ${response.status}` }; } const data = await response.json(); if (data.code !== 0) { return { success: false, error: `业务错误: code=${data.code}` }; } const items: DocItem[] = (data.data?.items ?? []).map((item: any) => ({ id: String(item.id), title: String(item.title ?? ''), url: String(item.url ?? ''), updatedAt: String(item.updatedAt ?? '') })); const total = Number(data.data?.total ?? 0); const result: SearchResult = { total, results: items, hasMore: page * pageSize < total }; return { success: true, data: result }; } catch (err) { return { success: false, error: `调用异常: ${(err as Error).message}` }; } } } export default DocSystemAdapter;

这段代码里有几个设计决策值得说明。

401 重试逻辑：即使有提前刷新机制，仍然可能因为时钟偏差或服务端主动失效导致 401。所以我在收到 401 时，强制清空 Token 并重试一次。注意这里用了递归调用this.callTool(name, args)，但要确保不会无限递归——因为ensureToken会重新登录，正常情况下第二次不会再有 401。

参数边界处理：page和pageSize都做了Math.max/Math.min限制，防止 AI 传入负数或超大值。pageSize上限设成 50，是因为服务端可能有限制，而且返回太多数据对 AI 也没用。

返回值归一化：把服务端的{ code, data: { total, items } }拍平成{ total, results, hasMore }。hasMore字段让 AI 知道是否需要继续翻页。

4.3 注册与联调

适配器写完后，需要在 OpenCLI 的配置里注册。不同版本的 OpenCLI 注册方式略有差异，但核心都是把适配器实例挂载到框架上：

import { OpenCLI } from 'opencli-core'; import DocSystemAdapter from './adapters/doc-system'; const cli = new OpenCLI(); cli.registerAdapter(new DocSystemAdapter({ baseUrl: process.env.DOC_BASE_URL!, username: process.env.DOC_USERNAME!, password: process.env.DOC_PASSWORD! })); cli.start();

联调阶段，我建议先用 OpenCLI 自带的工具列表命令确认适配器注册成功，然后手动构造几个典型调用测试。重点测三种情况：正常参数、缺参数、参数类型错误。这三种情况覆盖了大部分 AI 调用出错的场景。

联调时有个小技巧：在callTool里加临时日志，把收到的args和返回的result都打出来。这样当 AI 调用结果不符合预期时，你能快速判断是 AI 传参问题还是适配器处理问题。上线前记得把日志级别调低或移除，避免泄露敏感信息。

5. 常见问题与排查技巧实录

5.1 适配器注册后 AI 看不到工具

这是最常见的问题。表现是适配器代码没报错，但 AI 调用时提示「没有可用工具」。排查思路按顺序来：

先确认getTools()返回的数组非空，且每个工具的name字段符合命名规范（一般要求字母、数字、下划线，不能有空格和特殊字符）。我遇到过工具名里带了连字符导致注册失败的案例。

再确认parameters字段是合法的 JSON Schema。有些框架对 schema 的格式要求严格，比如type必须是字符串'object'而不是对象，required必须是字符串数组。可以用在线的 JSON Schema 校验工具过一遍。

最后确认适配器的name字段没有和其他适配器冲突。OpenCLI 一般要求适配器名称全局唯一，重名会导致后注册的覆盖先注册的。

5.2 AI 传参总是缺字段或类型错误

这个问题通常出在工具描述上。AI 是根据description和parameters里的描述来决定怎么传参的。如果描述写得含糊，AI 就容易猜错。

我的经验是：在参数描述里明确写出格式要求和示例。比如不要只写「搜索关键词」，而要写「搜索关键词，必填，例如：'季度报告'」。不要只写「数量」，而要写「返回数量，整数，范围 1-50，默认 20」。

另外，如果某个参数是枚举值，一定要在 schema 里用enum明确列出所有可选值。AI 对枚举的理解准确率远高于自由文本。

5.3 调用超时或响应缓慢

适配器调用外部系统，超时是常态。排查时先区分是网络问题还是业务问题。

网络问题的话，检查baseUrl是否正确、目标服务是否可达。我遇到过因为环境变量没配置导致baseUrl是undefined的情况，请求直接发到了错误地址。

业务问题的话，可能是目标接口本身慢，或者适配器做了不必要的串行操作。比如登录和业务请求如果串行，总耗时就是两者之和。可以考虑在适配器初始化时预热 Token，把登录耗时提前消化掉。

还有一个容易被忽略的点：fetch 默认没有超时。如果目标服务不响应，请求会一直挂着。建议在适配器里加一个 AbortController 做超时控制：

const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 10_000); try { const response = await fetch(url, { signal: controller.signal }); // ... } finally { clearTimeout(timeoutId); }

5.4 常见问题速查表

问题现象	可能原因	排查方向	解决方案
AI 看不到工具	工具名非法或 schema 格式错误	检查getTools()返回值	修正命名，用 JSON Schema 校验工具验证
参数缺失或类型错误	工具描述不清晰	检查description和parameters	补充格式说明和示例，枚举用enum
调用超时	网络不通或目标服务慢	检查baseUrl和网络连通性	加 AbortController 超时控制
401 认证失败	Token 过期或未正确传递	检查认证头和 Token 刷新逻辑	实现提前刷新 + 401 重试
返回值 AI 解析不了	返回结构太深或数据量太大	检查返回的data结构	拍平结构，限制返回条数
并发调用出错	Token 刷新竞争	检查是否有并发登录	用 single-flight 控制刷新
适配器注册失败	名称冲突或接口未实现	检查name和必需方法	确保名称唯一，实现全部接口方法

5.5 几个独家避坑技巧

技巧一：用环境变量管理敏感配置。适配器里不要硬编码账号密码和 baseUrl，全部走环境变量。这样本地开发、测试、生产可以用不同配置，也避免敏感信息进代码仓库。

技巧二：给适配器加健康检查。在适配器里实现一个healthCheck()方法，定期探测目标服务是否可用。OpenCLI 启动时可以调用一次，如果目标服务不可达就提前告警，而不是等 AI 调用时才报错。

技巧三：返回值里加「提示信息」字段。有时候 AI 需要一些额外上下文才能正确理解结果。比如搜索结果为空时，返回{ results: [], hint: '未找到匹配文档，建议尝试更宽泛的关键词' }，AI 看到 hint 后能给出更友好的回复。

技巧四：适配器版本号要维护。version字段不只是装饰，当适配器逻辑变更时，更新版本号能帮你追踪问题。我习惯用语义化版本，接口不兼容的变更升主版本号，功能新增升次版本号，bug 修复升修订号。

技巧五：日志脱敏。适配器日志里不要打印完整的 Token、密码、用户隐私数据。我一般只打印 Token 的前 8 位加省略号，密码字段直接替换成***。

6. 适配器编排与进阶扩展方向

6.1 多适配器协同工作的思路

单个适配器能解决「AI 调用一个系统」的问题，但真实场景往往是「AI 需要串联多个系统」。比如先查工单系统拿到工单号，再去文档系统查相关文档，最后去通知系统发消息。这就需要适配器编排。

OpenCLI 本身不直接提供编排能力，但可以通过两种方式实现。一种是在适配器内部调用其他适配器，把多个适配器的能力组合成一个更高层的工具。另一种是让 AI 自己编排，把多个适配器的工具都暴露给 AI，由 AI 决定调用顺序。

我实测下来，第一种方式更可控，适合流程固定的场景；第二种方式更灵活，适合探索性任务。但第二种方式对 AI 的规划能力要求高，容易陷入循环调用。我的建议是：核心流程用第一种方式固化，边缘场景用第二种方式兜底。

6.2 适配器的性能优化

当适配器数量增多、调用频率上升时，性能会成为瓶颈。几个优化方向：

连接复用。如果目标服务支持 HTTP/2 或长连接，适配器应该复用连接而不是每次新建。Node.js 的undici库在这方面比原生 fetch 表现更好。

结果缓存。对于变化不频繁的数据，适配器可以加一层内存缓存。比如文档系统的分类列表，可能几小时才变一次，缓存 5 分钟能显著降低目标服务压力。但要注意缓存失效策略，避免 AI 拿到过期数据。

批量接口。如果目标服务支持批量查询，适配器应该优先用批量接口而不是循环单条查询。我见过一个适配器循环调用 100 次单条接口，耗时 30 秒，改成批量接口后降到 1 秒。

6.3 适配器的测试策略

适配器的测试不能只靠手动联调，要写自动化测试。我的测试策略分三层：

单元测试测参数校验和返回值归一化逻辑。这部分不依赖外部服务，可以用 mock 数据跑，速度快、覆盖全。

集成测试测真实的 HTTP 请求。用一个测试环境的目标服务，或者用 mock server 模拟响应。重点测认证流程、错误处理、超时重试这些边界情况。

端到端测试测 AI 调用适配器的完整链路。这部分最难自动化，我一般用固定的测试用例手动跑，每次适配器变更后回归一遍。

写测试时有个坑要注意：不要依赖真实的外部服务做单元测试。外部服务可能不稳定、可能限流、可能数据变化，导致测试结果不可靠。所有外部依赖都要 mock 掉。

6.4 后续可以扩展的方向

适配器做熟之后，可以往几个方向扩展。一是适配器市场，把通用适配器（比如接入常见 SaaS 服务的）抽象出来，团队内共享。二是适配器生成器，根据 OpenAPI 文档自动生成适配器骨架，减少重复劳动。三是适配器监控，收集每个适配器的调用成功率、耗时分布，及时发现劣化的适配器。

我个人最看好的是适配器生成器这个方向。现在很多服务都提供 OpenAPI 文档，如果能自动把 OpenAPI 转成 OpenCLI 适配器，二次开发的效率能提升一个数量级。我试过写一个简单的转换脚本，能覆盖 70% 的常见场景，剩下的 30% 需要手动调整认证和返回值归一化逻辑。这个方向后续值得深入。

最后分享一个我在实际项目中体会最深的点：适配器的价值不在于「能调用」，而在于「稳定地、可预期地调用」。一个偶尔失败、错误信息含糊的适配器，对 AI Agent 的伤害比没有适配器还大，因为 AI 会基于错误的结果做出错误的决策。所以宁可少接几个适配器，也要保证每个接进来的都是经过充分测试、错误处理完善的。这个原则我在多个项目里验证过，确实能省下大量排查问题的时间。